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Preface 


This book has been developed for teaching programming using the IBM Operating 
System/2 (OS/2). It is suitable for a one-semester course in OS/2, as an adjunct to 
a course in operating system design, or as a vehicle for self-study on OS/2 program- 
ming. The emphasis in the book is on programming techniques for an advanced 
multitasking microcomputer operating system. Both Macro Assembler/2 and the C 
language are supported in the text. The OS/2 Application Programming Interface 
(API) services can be understood in either context. 

The text addresses the basic OS/2 kernel services: the video (Vio), Disk 
Operating System (Dos), keyboard (Kbd), and mouse (Mou) API functions. The 
latter service is most useful in a windowed display such as the Presentation Man- 
ager, which is omitted from this text. The book concentrates on the OS/2 Full- 
Screen Command Mode, which utilizes the entire display for presentation of a single 
program, making no other programs visible. Similarly, input and output under pro- 
gram control is implemented through the standard assembler or C syntax, such as 
printf() or scanf(). These operate in Protected Mode as well as Real Mode. Conse- 
quently, there is little need to incorporate specific keyboard API services into the 
program examples. Keyboard and mouse functions are discussed briefly in Appen- 
dix D. Some use is made of the keyboard services, for example, to pause the graph- 
ics screen. 

The Presentation Manager windowed interface is not developed in this book. 
Although this is a rich and complex interface, it is not considered suitable for a one- 


xi 
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semester course on OS/2 programming. The services at the level of IBM’s OS/2 
Standard Edition 1.0 are assumed as sufficient material for such an introductory 
course. When object-oriented programming tools become available for the Presenta- 
tion Manager and the burden for programming this interface is eased, it will be ap- 
propriate in a beginning course in OS/2 programming. 

During the late 1980s when OS/2 was developed, the principal major compet- 
ing operating system for advanced microcomputer applications was UNIX. OS/2 
follows IBM’s earlier microcomputer operating system, Disk Operating System 
(DOS), and runs DOS as a subset. UNIX has tended to be used more within the 
scientific and engineering community and is generally optimized for larger machines 
than the baseline microcomputers developed during this time frame. 

What are the advantages afforded by OS/2? OS/2 is predominantly a multi- 
tasking operating system capable of extensive memory management. It accomplishes 
these activities through hardware intervention based on the Intel 80286 chip set. 
(Hardware compatibility exists at the 80386 and 80486 levels.) There are four lev- 
els of protection provided (unlike the Motorola 68020 and 68030, for example, 
which have two); hence OS/2 can be tailored to handle the multitasking problem. 
The protection mechanisms provide coarse-grained through fine-grained memory 
management. This allows a detailed dynamic memory allocation at any given time. 

If we examine OS/2 in the framework of the near-term evolution of microcom- 
puter systems (1990s), it is apparent that changes in software development and 
applications will dictate about an order-of-magnitude increase in software complex- 
ity. It is clear that many efforts will give way to multithread and multiprocessor pro- 
gramming. The OS/2 multitasking features make it a good candidate for major 
microcomputer applications during the 1990s time frame. Also, the hardware protec- 
tion mechanisms mentioned above are suited for minimizing operational errors in 
such multitasking situations. Hence OS/2 is positioned to become the operating 
system of choice for high-end personal computer applications based on the Intel chip 
sets. 

OS/2 is particularly suited for user-friendly operation and programming. The 
API services are readily programmed in a fashion similar to the now-more-familiar 
Basic Input Output System (BIOS) interrupt calls. The Presentation Manager repre- 
sents a large-scale object-oriented interface. It is programmed in an almost identical 
manner to the Microsoft Windows Software Development kit (SDK) programming. 
OS/2 is moving rapidly toward widespread acceptance as the IBM microcomputer 
operating system for the early 1990s, just as DOS was for the 1980s. 

This book is intended to teach techniques on how to program in an advanced 
multitasking environment. The approaches required for software development reflect 
the solutions and compromises that exist in the 80286 hardware and the OS/2 Pro- 
tected Mode software. The power of OS/2 lies in its potential to run a number of 
large-scale applications simultaneously, with asynchronous and synchronous sharing 
of data. The use of pipes, queues, and semaphores (as well as shared memory 
blocks) ensures that intertask communication minimizes errors and follows well- 
established guidelines. 
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OS/2 is large, but experience has demonstrated a rather elegant superstructure 
that combines Microsoft Windows, DOS, multitasking, and memory management. 
Even in the scaled-down 80286 environment, OS/2 presents a very user-friendly 
interface to the hardware. Finally, all the programming skills developed for the 
earlier DOS framework are applicable when writing software for OS/2. IBM and 
Microsoft have maintained many philosophical features of DOS while incorporating 
the Apple MaclIntosh-like graphical interface in PM. OS/2 is truly an order-of- 
magnitude change in microcomputer operating systems. The potential for large-scale 
object-oriented applications is intrinsic to the PM definition. 

This, then, is the world of OS/2 as we move through the 1990s. The reader 
can expect a programming arena in which multitasking is important. This is a pre- 
cursor to the parallel processing systems coming toward the end of the decade. At 
the same time, implementation of segmented large-scale applications becomes a 
reality through interprocess communications and memory management. Thus effi- 
cient use of microcomputer resources becomes feasible. Finally, graphical interface 
techniques lead to very user-friendly application environments. OS/2 promises to be 
at the forefront of microcomputer operating systems because of all these features. 

One comment about the style used in this book. The IBM macro calls to the 
Application Program Interface (API) are used throughout. This is in keeping with the 
trend toward higher-level-language constructs and structured code when developing 
assembler programs. It does have the effect of obscuring the stack loading during an 
API call and assumes that the reader has access to the IBM API macros (i.e., the 
IBM Toolkit include files). The trade-off, however, is that fewer lines of program 
code need to be understood, and for someone familiar with the calls, the inferences 
are clear. This has implications for maintenance as well as debugging. 

This text is practically oriented. The examples are somewhat lengthy, by inten- 
tion and as a real-world case would be. They are intended for the serious student 
who is interested in programming under OS/2. The Color Graphics Adapter mode 
(CGA) is illustrated because of its relative simplicity and ease of programming. 
Also, it is a readily testable feature that can easily be programmed using C or as- 
sembler. The book assumes that the student has a basic familarity with C and as- 
sembler. 


ACKNOWLEDGMENTS 


As is to be expected, a great many people contributed to this book both knowingly 
and unknowingly. It is impossible to give credit in all cases; however, a few notable 
exceptions are my wife, Judy, who did all the typing and much of the editing; 
Marcia Horton, Editor-in-Chief at Prentice Hall, who was always available to answer 
questions and provide inputs; Ray and Agnes, my parents, who laid the groundwork 
for this book years ago, and Emma, Judy’s mother, who provided both of us with 
a sense of stability. Thanks to Kathleen Schiaparelli and her staff for their excel- 
lent job producing the book. 


xiv 


Finally, special mention should be made of the help I received on BIX, Byte 
Magazine’s bulletin board, for those unanswerable questions that plague every 
programmer and can be answered only by someone else. Like many other forums, 
BIX is an excellent place to go for answers because of the depth and breadth of ex- 
perience displayed by its membership. Also, the thoughtful comments provided by 
Margaret Mooney added a new perspective. 


Programming 
the Os/2 Kernel 


PART | 
Introduction to O$/2 


| The OS/2 Environment 


During the 1980s, IBM developed (in conjunction with Microsoft, Incorporated) the 
Disk Operating System (DOS) [1] as a primary operating system for its family of 
microcomputers: the IBM PC, XT, XT286, AT, PS/2 Models 25, 30, 50, 60, 70, and 
80. These systems were developed using the Intel family of central processor unit 
(CPU) chips, including the 8086, 8088, 80286, and 80386 [2-4]. DOS is a single- 
thread single-user system and hence is capable of executing only one task at any 
given time. Intel, however, provided the 80286 and 80386 with architectures that 
ensure hardware protection for multiple applications. This prevents code segments 
from being mixed during execution of multiple separate tasks. Such multitasking is 
the framework required by the advanced applications in existence and slated to 
arrive throughout the decade of the 1990s. 

Toward the end of the 1980s a clear need developed for an operating system 
that was capable of supporting and utilizing these advanced microcomputer hardware 
architectures. In response to this need, IBM and Microsoft developed Operating 
System/2 (OS/2) as their candidate to run on the Intel 80286-based (and 80386) 
machines [5,6]. There are many facets to OS/2. Both IBM and Microsoft have 
provided information needed to be able to program in the OS/2 environment through 
their Toolkit (IBM) [7] and Software Development Kit (Microsoft) [8]. Initially, 
following an early issue by Microsoft in 1987, IBM released OS/2 Standard Edition 
Version 1.0 in December 1987. This early version employed the full-screen com- 
mand prompt mode only, which initially displays a menu followed by a screen with 
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header. Basically, two modes were allowed: DOS compatibility mode, which runs 
from a screen with a typical prompt such as 


(C:\>) 


and runs DOS programs, and OS/2 Protected Mode, which runs from a screen with 
a typical prompt such as 

[Coe] 
In the fall of 1988 IBM released Version 1.1 of the Standard Edition, which in- 
cluded the Presentation Manager (PM) [9]. This provided a full Windows-like gra- 
phical interface to the user. This graphical interface is very similar to that found 
with the Apple MacIntosh operating system [10]. 

In addition to the Standard Editions, IBM and Microsoft have developed an 
Extended Edition, which has a local area network (LAN) interface and a database 
manager with support for Structured Query Language (SQL). The later editions of 
OS/2 (Extended Edition 1.0-10/88 and 1.1-11/88) function in essentially the same 
fashion as the Standard Edition; hence we will focus on the Standard Edition and 
not address the LAN and database features in this book. Basically, we are interested 
in programming highlights rather than specialized application packages. 

IBM recommends a minimum of 2 megabytes (MB) of random access mem- 
ory (RAM) for running Standard Edition 1.0, 3 MB of RAM for Version 1.1, and 
3 MB of RAM for the Extended Edition (EE). Also, the EE may completely con- 
sume a 20-MB hard disk drive [11]. Most versions of OS/2 come complete with 
the CodeView debugger, which is capable of debugging both assembler and C code. 
These are the two languages considered in this book. The language support for 
OS/2 is extensive with assembler, FORTRAN, BASIC, C, Pascal, and COBOL 
compilers existing. As indicated, we will focus on C [12] and assembler [13] for the 
OS/2 environment. Although IBM provides a Protected Mode editor with Version 
1.1, in the program development for this book, VEDIT PLUS [14] was used as a 
full-screen editor run from the DOS compatibility box. This process was quite 
smooth and allowed for early development when only Version 1.0 was available. 
Context switching between Real (DOS compatibility box) and Protected Mode was 
accomplished rather efficiently in the OS/2 implementation. Programming the Pres- 
entation Manager graphical interface is very much a Windows-like exercise [15]. 

With these introductory remarks in mind, where are we going with this book? 
The goal is to establish for the reader the capability to write programs in the OS/2 
kernel environment. We address code development in assembler (IBM Macro As- 
sembler/2) and C (Microsoft C Compiler Version 5.1). 

What is so unusual about OS/2 in relation to conventional Real Mode (Intel 
80286 Real Mode) programming? In OS/2 the major achievement is the definition 
of API services for access of the Protected Mode multitasking and memory manage- 
ment features. Typically, an entire new class of function calls is added to the usual 
assembler or C code. These functions (the API) constitute the system interface and 
have syntax (in ASM) like 
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@DosExit action, result 


instead of the normal return instruction, ret, or 


@VioScrLock waitf,iostat,viohdl 
@VioGetPhysBuf PVBPtrl,viohdl 


@VioScrUnLock viohdl 


instead of int 10H. Hence it is apparent at a glance that OS/2 function calls tend to 
require more parameters (versus register setup) than conventional assembler. They 
have the added attribute, however, of being a symbolically elegant interface. By the 
latter reference, we mean that the API services appear as a natural extension of 
assembler or C code in modular and complete fashion. 

OS/2 is a model operating system for illustrating advanced features in a sys- 
tems software framework. As discussed, it is somewhat RAM intensive, although it 
will run comfortably with 2 MB as an installed base. The principal accomplishment 
is the segregation of services for operation in the multitasking environment. How 
this segregation is accomplished is reflected in the programming techniques used to 
write code for OS/2. OS/2 is a good example of how multitasking should be imple- 
mented. 


1.1 HARDWARE CONSIDERATIONS 


OS/2 is written primarily for the architecture of the Intel 80286 (and is compatible 
with the 80386) as it exists in Versions 1.0 and 1.1 of the Standard and Extended 
Editions. The manner in which the hardware and software coexist depends largely 
on the Intel concept of segmented memory and the notion of levels of protection. 
We examine these aspects of OS/2 and attempt to correlate the register-level hard- 
ware with OS/2 address allocation. It is important to recognize, however, that keep- 
ing with the Intel philosophy of downward compatibility, subsequent microproces- 
sors in the 8086 family run code intended for the earlier chip sets. Hence the 80386 
architecture, although more advanced than the 80286, will support 80286 Protected 
Mode software. This means that OS/2 runs on 80386 machines as well. 


1.1.1 The 80286 and 80386 Architecture 


It is worthwhile examining the Intel 80286 (and 80386) architecture at this point 
because this implementation serves as the basis for development of programs such 
as OS/2. Once we have touched on this hardware foundation, we can forever assume 
that a starting point exists from which to explore the features of 80286 systems 
software. 

Intel started the 8086 family of microprocessors with initial entries that have 
16-bit addressing. This includes the 8086, 8088, and 80286 chips. The 80386 has 
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32-bit addressing and represents a major step forward, in keeping with the increased 
speed of these integrated circuits. What is the major limitation of the 16-bit archi- 
tecture? In a physical sense (based on the actual wiring of circuits and memory) 16 
bits provides only 2'° or 65,536 possible individual references. This is the usual 64K 
segment. Recognizing that this constituted a very limited memory capability, Intel 
expanded the addressing concept to allow for multiple segments by providing a set 
of segment registers used to hold segment addresses. (This was in addition to the 
16-bit instruction pointer that held an offset into the code segment, for example.) 
When IBM implemented the Real Mode operating system DOS, a 1-MB address 
limit was built into the architecture which was based on a 20-bit address. Address- 
ing was accomplished by shifting the segment address left 4 bits, appending a zero 
(hexadecimal) to the segment address, and adding the offset to get the five-digit 
hexadecimal physical address. For example, assuming a segment address 10AF and 
an offset FOFF this physical address is 


10AFO _ — (segment address) 
FOFF (offset address) 
1FBEF — (physical address) 


where the usual notation would be 1OAF:FOFF. What are the register structures used 
to support this addressing scheme? In the 8086 and 8088 the following registers 
exist: 


Data 


AX the Accumulator: This register can be used for general programming 
storage. 


BX the Base Register: This register is frequently used to hold address val- 
ues when accessing memory. 


CX the Count Register: During loop operations this register holds the 
count index. 


DX the Data Register: This register is used for general storage. 
Segment 
CS the Code Segment Register: This register points to the beginning of 


the code segment block. 


DS the Data Segment Register: This register points to the beginning of 
the data segment block. 


SS the Stack Segment Register: This register points to the beginning of 
the stack segment block. 


ES the Extra Segment Register: This register points to the beginning of 
the extra segment block. 
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Pointer 
SP the Stack Pointer: This register holds offset values for the stack. 
BP the Base Pointer: This register holds offset values into the data seg- 
ments. 
Index 
SI the Source Index: This register holds an index offset in memory and 
frequently references the instruction source. 
DI the Destination Index: This register holds an index offset in memory 


and frequently references the instruction destination. 


Added to these 12 registers are the instruction pointer (IP) and flags registers, yield- 
ing a total of 14 16-bit registers for the 8088 and 8086. 
The 80286 enhances this register set with the addition of five registers: 


GDTR the Global Descriptor Table Register: This register points to system 
resource segments. 


IDTR the Interrupt Descriptor Table Register: This register points to inter- 
rupt service routine segments. 


LDTR the Local Descriptor Table Register: This register points to the 
active local program code segment. 


TR Task Register: This register holds the code segment address for the 
current task. 


MSW the Machine Status Word Register: This register sets up the proc- 
essing for real or Protected Mode. 


These Protected Mode registers plus some others are used by the operating system 
to provide proper address allocation during execution of an active Protected Mode 
task. 

Figure 1.1 illustrates a typical 80286 central processor unit (CPU) environment. 
Here the parallel external bus structure is apparent. The 80286 control of both the 
private and public system buses is via bus controllers (typically, an Intel 82288 and 
82289 combination). In the IBM AT and PS/2 Model 50 and 60 such a bus struc- 
ture exists with a representative architecture as depicted in Figure 1.2. Both these 
figures are similar and illustrate the parallel bus structure typical of 80286 systems. 
The private system bus contains localized private input/output (I/O) processing and 
buffering such as RS-232C adapters and video adapters, which constitute external 
physical entities. These are frequently accessed using direct memory access (DMA) 
controllers. The 8259A programmable interrupt controller (PIC) interfaces external 
hardware interrupts to the CPU. Both the private and public system buses have a 
three-part architecture: a control, address, and data bus subset. Control bus interfaces 
are handled by an 82288 bus controller with associated address decode logic (this is 
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typically implemented using LS138 decoder/demultiplexers) [16,17]. The address 
l/O is handled using latches, which hold and strobe address data onto the system 
buses in response to enable signals. Finally, data is placed on the data bus using 
transceivers (typically, the LS245 transceiver). 


PRIVATE SYSTEM BUS PUBLIC SYSTEM BUS 

| | PROCESSING 

| | MODULE 

ES 1/0 ect | pe can | SYSTEM 

ES ect | can | MEMORY 

SYSTEM I/O 
CONTROLLER 
Sor Sv) BUS 
DIRECT ea 
MEMORY PROCESSOR ee e 
ACCESS (DMA) EXTENSION 


CONTROLLER 


Figure 1.1 Representative 80286 system environment illustrating local and system buses. 


Figure 1.3 illustrates a representative memory and port allocation of address- 
ing among public and private spaces. For low memory, a 1-MB partition is illus- 
trated from 0H to OFFFFFH (here H indicates hexadecimal). This corresponds to the 
DOS partition in the IBM microcomputer address space. Local firmware is illustrated 
at the top end of the 16-MB physical memory space (OFFFOOOH to OFFFFFFH). 
This would be in the OS/2 extended memory area. In the IBM systems, erasable 
programmable read-only memory (EPROM) exists between portions of the 640K and 
1-MB address area, in what is designated as private system memory in Figure 1.3. 
Finally, the bulk of the public system memory resides above 1 MB. In OS/2 imple- 
mentations, this extended memory exists from 1 MB to 16 MB. 

The 80386 uses double-word arithmetic. The eight general registers are 32-bit: 
EAX, EBX, ECX, EDX, ESI, EDI, ESP, and EBP. The prefix E indicates that the 
familiar 16-bit general registers (AX, BX,...) have simply been extended to 32 bits. 
In fact, the low-order word of each of these eight registers can be treated as the 
equivalent 16-bit register with all the reserved name definitions applied to these 16- 
bit quantities. (The data registers further subdivide into byte-length register halves 
AH, AL, BH, BL,....) Clearly, this implies a downward compatibility for running 
16-bit microprocessor (8088, 8086, and 80288) code. 

The instruction pointer (EJP) and flags register (EFLAGS) have similar down- 
ward compatibility features. Finally, there are six segment registers: CS, DS, ES, SS, 
FS, and GS. The last two are new and provide for additional independent data 
segment access using overrides. These segment registers are each of word length. In 
addition to the registers specified, we have the following new system register types 
(plus the memory-management registers specified above): 
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1. Control registers (four): CRO, CR1, CR2, CR3 
2. Debug and test registers (eight): DRO, DR1, DR2, DR3, DR4, DR5, DR6, 


DR7 
MEMORY ADDRESS 
SPARE 
FFFFFFH 
LOCALERROR |eeroogoy 
PORT ADDRESS 
SPARE 


PUBLIC FFFFH 


SYSTEM 
MEMORY 


PUBLIC 
VO 


100000H 100H 


PRIVATE 
SYSTEM 
MEMORY 


PRIVATE 
VO 


OH 


Figure 1.3 Representative memory and port allocation among private and public 
address spaces. 


What does all this mean in terms of OS/2? Basically, the hardware manipula- 
tion of addressing under OS/2, and established by the link/locate operation in re- 
sponse to programmed instruction sequences, must occur so that no segment viola- 
tions take place in system memory. This is the topic of the next two subsections, 
where operation is described for a Protected Mode installation. We will observe that 
the 80286 registers are the primary vehicle for ensuring Protected Mode isolation of 
tasks. 


1.1.2 Hardware Operation for Protected Mode 


The main system memory of an 80286 system is organized as a sequence of 8-bit 
addressable quantities called bytes. The addressing spans the range 0 to 27° (1 MB) 
in Real Address Mode and up to 274 (16 MB) in Protected Mode. In Protected Mode 
no direct access to physical memory is allowed. The physical address space, for 
example, is controlled by 24 address pins from the 80286 chip itself. This dictates 
the 16-MB physical limit. Composition of the address space in Protected Mode, 
however, indicates a virtual address capability that is much larger. Basically, the 
80286 can access a collection of roughly 16,384 linear subspaces or segments each 
with a maximum size of 64 KB. This translates to a virtual memory size of 2*° 
bytes or 1 gigabyte (GB). The virtual memory allocation must map to physical 
memory for actual operation, using extended storage where needed. The notion of 
segmentation as described here allows programs to execute faster and requires less 
space, than does nonsegmented bulk linear addressing. 
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How does this protected virtual address mode manage memory? The segment 
selector is used. A particular segment is uniquely referenced by its selector, a 16-bit 
address with the following form: 


Ec) a 


Index Tl RPL 


Here TI is the table indicator, which references a global space when set or a local 
space when zero. The global address space is used for systemwide data and code. 
The local address space is for general code and data applications such as user tasks. 
The first two selector bits are the requested privilege level (RPL) bits and relate to 
protection. This leaves 13 bits, which when coupled with the TI bit allow a segment 
address space of 2'* segments, as discussed above. We will see the impact of pro- 
tection shortly, but it will be useful, briefly, to explore these segment descriptors 
further. Note that the descriptor table registers point to tables that provide a com- 
plete description of the global address space (GDTR), one or more local address 
spaces defined dynamically by the LDTR, and an interrupt address space (IDTR). 

Within a descriptor table two main classes are recognized: segment descriptors 
and special-purpose control descriptors. Figure 1.4 illustrates a descriptor. They pro- 
vide the physical memory base address, segment size, transfer data, and access data. 
The special-purpose control descriptor is very similar. There is a global and several 
local descriptor tables as alluded to earlier. (It is these tables that are pointed to 
using the GDTR and LDTR.) 


ACCESS RIGHTS BYTE 
7 07 0 


INTEL RESERVED 


P| oc | 1 IPE BASE (23-16) 


BASE (15-0) 


ACCESS RIGHTS BYTE 


P = Present 

DPL = Descriptor Privilege Level 
Ss = Segment Descriptor 
TYPE = Segment Type 


A = Accassed Figure 1.4 80286 segment descriptor. 
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The 16-bit selector is mapped to a descriptor table entry with its subsequent 
24-bit base address. The TI bit determines whether the GDT or a LDT is to be se- 
lected. The INDEX field specifies the particular descriptor entry within the chosen 
table. To get this descriptor entry the processor simply multiplies the index value by 
8 in hardware and adds the result to the descriptor table base address. 

The segment address translation registers can be depicted as follows: 


Visible | 48-Bit Hidden Descriptor Cache 


63 48 47 40 39 16 15 0 
16-bit Access Segment base Segment size 
selector rights address 


Here the last 16 bits (bits 48-63) comprise the CS, DS, SS, or ES register values. 
These bits are the visible portion of the translation register. By loading a segment 
selector into one of these registers, the program makes the associated segment one 
of its four currently addressable segments. Note that the definition of the segment 
base address, the physical address associated with the 16-bit segment selector, must 
be correlated with the selector by the system software. It is this correspondence 
between the 16-bit selector and the segment base address that permits virtual ad- 
dressing to function properly. Both of these addresses, along with the access rights 
byte and segment size (the translation register contents), permit the correct mapping 
of virtual memory to physical memory by OS/2, for example. It is here, then, that 
the algorithms developed in the systems software effect the actual mapping of 
memory, and the content of this segment address translation register serves as the 
basis for this mapping. 

Figure 1.5 illustrates the protection levels permitted by the 80286 RPL selec- 
tion. The two bits provide for four levels of protection. In this figure level 0 is the 
most trusted and level 3 the least. Privilege level is a protection attribute assigned 
to all segments. Privilege checks are made automatically by the CPU hardware. Pro- 
grams at level 0 may access data at all other levels, while programs at levels 1-3 
may access data only at the same or a less trusted level. 

How does OS/2 make use of these levels? Typically, software at level 0 in- 
cludes services such as memory management, task isolation, intertask communica- 
tions, and I/O resource control. Level 1 is designated system services and provides 
functions such as file access scheduling, character I/O, and data communications. 
Level 2 corresponds to reserved space for customized applications such as database 
managers, spreadsheets, and word processors, as well as background tasks. Finally, 
level 3 contains general-purpose user application of the sort written about in the ex- 
amples in this book. Privilege applies to tasks and affects three different categories 
of descriptors: 
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1. Main memory segments 
2. Gates (used to change code segments) 
3. Task state segments 


APPLICATIONS 


EXTENSIONS 


SYSTEM 
SERVICES 


Figure 1.5 Protection-level software 
allocation and priority, based on level 
hierarchy, for the Intel 80286. 


Descriptor privilege is assigned when the descriptor is created. We have seen, for 
example, how segment descriptors are formed with their access rights byte and RPL 
bits controlling protection. 

Three kinds of control transfers can occur within a task: 


1. Intrasegment transfers 
2. Intersegment transfers at the same privilege level 
3. Intersegment transfers to different privilege levels 


The interlevel transfers must check for access permission and must ensure that a 
correct entry address is used. To achieve these control transfers, the gates indicated 
earlier must be used. 

A gate is a four-word control descriptor used to redirect a control transfer to 
a different code segment in the same or a more privileged level or to a different 
task. There are four types of gates: call gates, task gates, interrupt gates, and trap 
gates. All four gates define a new destination selector (16-bit), and offset (16-bit), 
which specifies the physical address to which the transfer is to take place. Call gate 
descriptors are established for call and jump instructions in the same manner as a 
code segment descriptor. Task gates specify intertask transfers for the initialization 


12 The OS/2 Environment Chap. 1 


and establishment of child tasks, information exchange, and synchronization. Inter- 
rupt gates permit system-level access of low-level hardware-driven interrupt services, 
and trap gates transfer control to system exception-handling services. 

Finally, task state segments are a special control segment defined uniquely for 
each task. They include the definition of the task address space and execution state. 
This segment has a special descriptor whose selector is contained in the Task 
Register. Each task state segment contains 22 words, including the current general- 
purpose register values and the SS and SP values for each current protection-level 
stack (there are four such stacks). The descriptor contains the task descriptor privi- 
lege level and the usual segment base and limit values. Hence protection mecha- 
nisms are extended to intertask control transfers using task state segment descriptors. 
Task switching is accomplished by loading the Task Register with the new task 
selector, marking the new task’s descriptor type as busy, and setting the Task 
Switched bit in the Machine Status Word (MSW). This MSW bit signals that the 
context of the processor extension (80287, for example) may not belong to the 
current task. 

So far we have looked at the 80286 hardware for Protected Mode operational 
features. These hardware features allow system software such as OS/2 to develop 
strong protection mechanisms in multitasking environments. Without this protection 
implementation of the software would necessarily be much more difficult to develop 
and software protection mechanisms would be required rather than a reliance on 
register bit monitoring. The room for error in such systems software becomes sub- 
stantially greater as application complexity increases. 


1.1.3 Software Operation for Protected Mode 
The flag word for the 80286 is 


SOO ODO OM One 


IOPL OF DF TF SF ZF 
where 
CF Carry Flag (set on high-order bit carry or borrow) 
PF Parity Flag (set if low-order byte contains an even number of 1’s) 
AF Auxiliary Flag (set on carry or borrow to low-order nibble) 
ZF Zero Flag (set if result 0) 
SF Sign Flag (0 if positive or 1 if negative: high-order bit of result) 
TF Trap Flag (single-step mode) 


IF Interrupt Flag (causes CPU to transfer control to a vector location) 
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DF Direction Flag (causes string instructions to auto-decrement when 
set) 

OF Overflow Flag (set if result is too large) 

NT Nested Task Flag (when set causes a return to the calling task for 
IRET) 


IOPL IO Privilege Level (specifies current task privilege level) 
The Machine Status World (MSW) has the following format: 
2 SRN 5.52 52 i 
Used by 80386 TS EM MP PE 
where 


PE Protected Enable (places 80286 into protected mode) 
MP Monitor Processor (allows WAIT states to be introduced for the 


80287) 
EM Emulate Processor (allows the 80287 to be emulated) 
TS Task Switched (allows test to determine if 80287 context belongs to 


current task) 


It is clear that modifications to the flag word (IOPL and NT) permit added 
software checking for Protected Mode status based on hardware. The MSW provides 
a software mechanism for checking coprocessor status with regard to the current 
80286 program context. In addition to these changes, a number of instructions have 
been added to the basic Real Address Mode set which reflect privileged and trusted 
operation. Instructions such as the following fall in this category of enhanced soft- 
ware instruction capability to support Protected Mode. 


SMSW _ Store MSW 

LIDT Load interrupt descriptor table register 
LMSW Load MSW 

CLIS Clear task switch flag 

LGDT Load global descriptor table register 
LLDT Load local descriptor table register 
Lik Load task register 

SGDT Store global descriptor table register 
SLDT Store local descriptor table register 
SIDT Store interrupt descriptor table register 
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These instructions are generally available only to system software. Once an operat- 
ing system is established (such as OS/2) for the system, privilege-level access must 
be regulated within the constraints of this system. The user, for example, cannot 
arbitrarily insert code at privilege level 0. During software implementation under 
OS/2, privilege-level access is regulated by the OS/2 system software and API serv- 
ice calls for normal application development. This sort of application development 
is the type treated in this book. 


1.2 A BRIEF LOOK AT OPERATING SYSTEM/2 


Figure 1.6 presents a simplified OS/2 architecture. This figure reflects the component 
parts needed to define operating systems software completely [18—21] and illustrates 
both the multitasking and memory management functions. As with most architec- 
tures, Figure 1.6 is a mix between static entities, such as loaders, and dynamic 
activities, such as intertask communications. The intent of the figure is to portray 
hierarchical relationships [22-25] for OS/2. 

Before we examine the major individual features of the IBM OS/2 implemen- 
tation, it will be useful briefly to discuss Figure 1.6. This architecture attaches equal 
importance to the 80286 (or 80386) hardware protection implementation and OS/2 
itself. Without the hardware mechanisms OS/2 would be a much bulkier and more 
sluggish operating system. Hence the Intel chip architecture deserves a substantial 
amount of credit for yielding an optimized multitasking executive. The dominant 
mechanism for installing multitask protection is the definition of privilege based on 
hardware monitoring and checking. This mechanism is put in place in the software 
during system initialization. The loader and kernel act at level O to define the 
baseline operating system. Device service is handled through the device drivers, 
which consist of three parts: 


1. An initialization routine 
2. A strategy routine 
3. An interrupt routine 


The initialization routine initializes the device by setting the device registers with 
proper data to establish mode of operation, and this routine also establishes any data 
structures (buffers and parameter data) needed by the device during operation. The 
strategy routine receives I/O requests from the kernel and initiates I/O. The Interrupt 
Service Routine (ISR) is the only OS/2 program privileged to accept and process 
hardware interrupts (signals on IRO-IR7 of the two 8259A PICs in the IBM PC AT, 
for example). The device service routines call DevHIp functions in order that the 
ISR can access application buffers from the kernel. I/O Protection Level checking is 
continuously monitored to validate what buffers may be accessed by the drivers. 
Other API functions are used to ensure proper physical memory segmentation, for 
example, as is the case with screen buffer access. 


Japeo7 


uogeoiddy 


suoloun 
Aeydsiq 
pealydess 


BORO} UI 
esno- 


Buissao0ld 


ebessoy 


eAgnoeXxy 
Wd 


eorypa}y| 
esno; 


Japeo7 
uoneoiddy 


eoep9}uU] 
Ke\dsig \xeL 
psepuels 


Jasied 
puewwog 


preoqhey 
/OIA 


‘aInjoayose 7/SQO WAI 9° aandig 


ysel 
yUsLIND 


uogeUuIWe | 
ySeL 


S8SS900! ened 
d SUOReDIUNWLWOD UWEYS sselppy 
| uewBbe 
pllud Y4SELO}U| y s peyoajold 


UOfepl|BA 
_— juewebeuryy 
PeptelsS UO|SS|LWOd 


SS8901d JaBeueyy juewebeueyy eer 
JUSpISay ysel Req me : 


eacireait 8ANNOBXA 
lasp e/SO 
uolejuawajdwy| 
UOI}O9JOld 
eJeMpJeH 


98¢08 


wayskS 
Wal 


SIOAIQ 
69/A8Q 


1dOl 


O/| Puy 
GO|ME8S 
89|A8Q 


c/SO 


(0 eae) 
jowey 


Jepeo7 
P8}998}Old 


UORe2Z|[e3|U] 
2/SO 


15 


16 The OS/2 Environment Chap. 1 


The OS/2 executive is the main processing element of the architecture. This 
routine contains the core loop, which is the infinite loop sequence representing the 
idle system state and which may only be affected by a hardware interrupt such as 
the striking of a key on the keyboard. The executive has four components: file 
system management, data management, task management, and data segment defini- 
tion. All objects in the system represent named entities and are subject to file 
management rules. File permission and protection validation is conducted at a rela- 
tively high level in software. At a lower level, the protected address allocation 
requires privilege-level authority. 

Data management is an extension of file system management. This component 
of the executive ensures that segmentation violations do not occur because proper 
allocation is implemented. It manages extended files (disk and diskette files, for 
example). It handles the movement of data in a virtual memory context where the 
amount of virtual memory required for data, for example, can exceed the total 
available physical memory in the system. (This is also true for other memory types, 
such as program memory.) Segment sharing among tasks and other interprocess 
communication activities involving the access of data segments are managed by this 
component. 

The task manager is the primary dynamic activity element during program 
execution. We use the terms thread and process assuming some familiarity with 
these abstract concepts. Briefly, a thread provides program instructions and data in 
an execution environment that consists of registers, stacks, and CPU dynamics. 
Threads do not have system resources allocated to them, but may call or access such 
resources under the umbrella of a process. Here a process is a collection of threads 
and system resources allocated to a program. OS/2 task management includes sched- 
uling with a preemptive time-slicing dispatcher. This type of dispatcher is operated 
on a polling model concept where each thread has a fixed period of time during 
which it may execute (the time slice) before control is taken away (preempted) and 
the next thread rolled in and allowed to execute. The process continues in wrap- 
around fashion, and each time slice executes for an approximately equal length of 
time (at a given privilege level), which is dynamically allocated based on the 
number of threads active in the system. Task initialization is established by the task 
manager at level O and involves service calls of the type DosCreateThread or 
DosExecPgm. 

Intertask communications typically involve semaphores, pipes, and queues. 
Also, shared memory segments can be used to pass data among threads and pro- 
cesses. A semaphore is a data structure that OS/2 passes to only one thread at a 
time. This provides for a rudimentary serialization when two threads, for example, 
need to access a common data area. OS/2 implements two kinds of semaphores: sys- 
tem and RAM semaphores. System semaphores are used for communication between 
processes and are implemented by DosCreateSem, for example. RAM semaphores, 
on the other hand, are used between threads in a single process. 

Pipes are buffer areas created by DosMakePipe and are accessed using pipe 
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read and write handles in much the same fashion that conventional file handles are 
used to access files. To use a pipe to communicate with another process, the pipe is 
first created and then one of its two handles (read or write) is passed to the second 
process using a common data structure. In accessing buffers via pipes the data is 
treated as a continuous stream. An alternative interprocess communications tool is 
the queue generated by the DosCreateQueue service. Here the data is viewed as an 
individual collection of finite-length elements that may be separately addressed or 
accessed. The major feature of the queue is the variability with which data elements 
may be accessed. 

Termination of a communication or task is typically initiated by API calls of 
the type DosCloseQueue, DosCloseSem, or DosExit. Finally, the task manager is 
responsible for maintaining all thread parameters on the local thread stack during 
roll-out by the dispatcher. When a task has been preempted it must maintain point- 
ers to entry points in the code and associated data segments that reflect its current 
execution position. This is what the task state segment contains, and the task 
manager is responsible for establishing and maintaining this segment. Data segments 
must, of course, be defined at the proper privilege level and accessed only with the 
proper privilege authority. This is also a function of the OS/2 executive. 

The user interface represents OS/2s interaction with the outside world. Two 
visual displays are possible: the VIO or full-screen command mode and the Presen- 
tation Manager (PM), a windowed mode where visual data from multiple tasks can 
be presented. The VIO has a familiar DOS-like screen. The PM is a dynamic dis- 
play environment capable of simultaneously illustrating multiple program execution 
through overlapping windows of the type found in the Microsoft Windows program 
and similar to the Apple MacIntosh display. The PM coordinates activity internally 
by exchanging messages among tasks and the PM executive. A preferred interface 
technique is the mouse, which moves a cursor around the screen. When the cursor 
is placed on a system or menu operation and the mouse single- or double-clicked, 
the command is executed. This requires an extensive command interpreter based on 
messages returned to the PM executive. 


1.2.1 Protected Mode 


In the discussion so far we have alluded to the API service routines. These are the 
topics of the next section, but it must be emphasized that they are a consequence of 
the Protected Mode implementation. Before examining the API, however, it is useful 
to look briefly at some of the Protected Mode operational considerations. 

When Real Address Mode its initialized and executes, the boot record causes 
the code segment register eventually to load with FOOO and the instruction pointer 
to load with FFFO. This address points to a private memory segment that provides 
64K bytes of code space for initialization code without changing CS. During initiali- 
zation of Protected Mode, several registers must also be initialized: Both the GDT 
and IDT base registers must point to a valid global descriptor table and interrupt 
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descriptor table, respectively. The 80286 next executes the LMSW instruction to set 
the protected enable (PE) bit and must follow this with an intrasegment JMP 
(unconditional jump) instruction to clear its CPU instruction queue of instructions 
decoded in Real Address Mode. To initialize the 80286 registers for the initial 
Protected Mode state the JMP instruction executes with a selector referring to the 
initial task state segment address used in the system. This loads the task register, 
LDTR, segment registers, and remaining general registers with the initial Protected 
Mode parameter data. The TR should point at a valid task state segment. 

We have seen a general description of Protected Mode features. The 80286 
mechanisms to protect critical instructions (that affect CPU execution states such as 
HLT, halt) have three attributes: 


1. They involve restricted usage of segments, with the only segments available 
for use by applications defined by the LDT and GDT. 


2. They involve restricted access to segments via privilege. 


3. They include privileged instructions or operations that may be executed only 
at privilege levels determined by the current privilege level and I/O Privilege 
Level (IOPL). 


These mechanisms yield checks that are performed for all instructions and include 
segment load checks, operand reference checks, and privileged instruction checks. 
Operand reference errors would include writes to the code segment or segment limit 
exceeded, for example. Finally, an example of a privileged instruction exception or 
error would be the execution of an IN or OUT (port input or output instruction, 
respectively) instruction when the current protection level for the executing task is 
less trusted than the required IOPL. 

Four types of control transfer can occur when a selector is loaded into CS: 
intersegment with the same privilege level, intersegment to the same or higher-privi- 
lege-level interrupt, intersegment to a lower privilege level, and a task switch. We 
have already briefly considered these transfers, but what are the privilege rules 
associated with these transfers? The rules are as follows: 


1. JMP or CALL direct to a code segment can only be to a segment with de- 
scriptor privilege level greater than or equal in privilege to the current privi- 
lege level. 


2. Interrupts within a task or calls that may change privilege levels can only 
transfer control through a gate at the same or a less privileged level (than the 
current privilege level) to a code segment at the same or more privileged level 
(than the current privilege level). 


3. Return instructions that do not switch tasks can only return to a code segment 
with the same or less trust. 

4. A task switch can be performed by a call, jump, or interrupt that references a 
task gate or task state segment of the same or less trust. 
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Any violation of these descriptor privilege-level rules will result in exception 13, 
indicating a segmentation violation. 

A task has a current privilege level (CPL) defined by the lower two bits of the 
CS register (in the selector), as we have seen. CPL can change only when CS 
changes, using a control transfer through gate descriptors to a new code segment. 
Tasks begin executing at the CPL specified by the task switch’s resulting code 
segment. Tasks executing at level 0 can access all data segments defined in both the 
GDT and the task’s LDT. Any control transfer that changes CPL within a task 
requires a change of stacks. Initial values of SS and SP for privilege levels 0, 1, and 
2 are maintained in the task state segment. The values for level 3 are de- 
fined by the application and affect such transfers as establishing a new thread using 
DosCreateThread. 

These brief remarks about the Protected Mode are intended to put the hard- 
ware implementation in perspective. We have seen how privilege-level monitoring, 
for example, serves as a basis for segment access during execution. The 80286 
hardware features include rules and rule checking to maintain privilege integrity, and 
this preserves proper task operation in a multitasking environment. 

Generally speaking, data such as the GDT, initial task state segment, and 
system services will be located in erasable programmable read-only memory as part 
of the system build. These are all loaded during the bootstrap process and precede 
the actual OS/2 executive load and initialization. The foregoing discussion presents 
the salient 80286 features applicable to a consideration of how OS/2 avoids segment 
violations. This is the cornerstone for multitasking and memory management. The 
80286 Protected Mode attributes are summarized briefly in Table 1.1. 


1.2.2 API Services 


The Application Program Interface services have been mentioned a number of times 
so far in the discussion, and Table 1.2 lists these functions (for Version 1.0), indi- 
cating whether or not they are conventional API (all the OS/2 services comprise the 
API, or a subset of the API, the DOS family API, which corresponds roughly to the 
BIOS and DOS services and runs under the DOS compatibility box as well as the 
Protected Mode). 

The API services are based on the CALL instruction rather than the INT 
instruction. These API functions act in similar fashion to conventional higher-level- 
language (HLL) routines with their individual stacks and local parameter spaces. For 
OS/2 programs written in assembly language, the API service request can be cum- 
bersome. On the other hand, these CS/2 service implementations add an elegance to 
the resulting code that with just a few exceptions enhances modular development. In 
a higher-level-language context the API services improve modularity and structure. 
We will see examples of the use of these services in an assembly language and C 
context throughout the remainder of this book. Basically, however, the API is most 
desirable in a HLL environment. 
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TABLE 1.1 
Feature 


I/O protection 


Privilege levels 


Address protection 


Memory attributes 
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80286 PROTECTED MODE FEATURES 


Discussion 


To help manage I/O activities such as setting/clearing interrupts 
and port read/writes, the 80286 implements an I/O Protection 
Level (IOPL). This flag defines the minimum protection level 
at which a program must execute to perform I/O. This 
provides operating system control of the hardware. 

The 80286 provides for four levels of protection: 

1. PLO (Privilege 0): Most trusted; can access data at levels 
OU, 1, 2, and 3, 

2. PL1 (Privilege 1): Can access data at levels 1, 2, and 3. 

3. PL2 (Privilege 2): Can access data at levels 2 and 3. 

4. PL3 (Privilege 3): Least trusted; can access data at 3. 


Through use of LDTs each application program is allocated a 
private memory space. No other tasks are allowed to enter or 
use a given task's LDT area. Any common memory elements 
must be shared using the GDT. 


These attributes are specified in the descriptor table access byte. 
They include such features as read/write access and descriptor 
privilege level as well as a flag to indicate execution only 
(versus addresses associated with variable allocation). 


TABLE 1.2 APPLICATION PROGRAMMING INTERFACE ROUTINES 


Name 


Tasking 


DosCreateThread 


DosCWait 


DosEnterCritSec 


DosExecPgm 


DosExit 


DosExitCritSec 


DosExitList 


DosGetInfoSeg 


DosGetPrty 


DosKil]Process 


DosPtrace 
DosSetPrty 


API FAPI Description 
X Creates asynchronous thread 
X Places current thread in wait state 
X Disables thread switching 
Xx Allows another program to 
execute a child 
X Issued at completion of execution 
X Reenables thread switching 
Xx Maintains an exit list for routines 
X Returns the address of a data 
segment 
Xx Gets the priority of the current 
thread 
X Terminates a process 
X Interfaces to kernel for debugging 
X Changes priority of child process 


Asynchronous Notification 


DosHoldSignal 


X Changes signal processing 
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TABLE 1.2 (Continued) 


Name API FAPI 


DosSetSigHandler 


Interprocess Communication 


Description 


Notifies OS/2 of a handler for a 
signal 


DosCloseQueue X Closes a queue 

DosCloseSem X Closes a semaphore 

DosCreateQueue X Creates a queue 

DosCreateSem X Creates a semaphore 

DosFlagProcess X Allows a process to set an 
“event” flag 

DosMakePipe x Creates a pipe 

DosMaxSem Wait X Blocks until semaphore clears 

DosOpenQueue X Opens queue 

DosOpenSem X Opens semaphore 

DosPeekQueue x Examines element in queue 

DosPurgeQueue X Purges a queue 

DosQuery Queue X Finds the size of a queue 

DosReadQueue X Reads an element from a queue 

DosResumeThread X Restarts a thread 

DosSemClear X Clears a semaphore 

DosSemRequest X Obtains a semaphore 

DosSemSet X Sets a semaphore 

DosSemSetWait X Blocks a thread until a semaphore 

DosSem Wait X Waits for a semaphore to clear 

DosSuspendThread X Temporarily suspends thread 
execution 

DosWriteQueue X Adds an element to a queue 

Timer 

DosGetDateTime Xx Gets the current date/time 

DosSetDateTime X Sets the date/time 

DosSleep Xx Suspends the current thread 

Memory Management 

DosAllocSeg X Allocates a segment of memory 

DosAllocShrSeg X Allocates a shared segment 

DosAllocHuge X Allocates multiple memory 
segments 

DosCreateCSAlias X Creates a code segment descriptor 

DosFreeSeg X Reallocates a memory segment 

DosGetHugeShitt Xx Returns a shift count for deriving 


selectors 
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TABLE 1.2 (Continued) 


Name API FAPI Description 
DosGetShrSeg Xx Accesses shared memory 
DosGetSeg X Accesses shared memory 
DosGiveSeg X Yields shared access to another 

process 
DosLockSeg X Locks a discardable segment 
DosMemAvail X Returns size of largest free block 
DosReallocHuge X Changes huge memory size 
DosReallocSeg X Changes segment size 
DosSubAlloc X Allocates from a previous 
allocated segment 
DosSubFree X Frees from a previous allocated 
memory 
DosSubSet X Initializes a segment 
DosUnlockSeg X Unlocks a discardable segment 
Dynamic Linking 
DosFreeModule X Frees a dynamic link module 
DosGetModHandle X Returns handle for dynamic link 
module 
DosGetModName X Returns pathname for dynamic 
link module 
DosGetProcAddr Xx Returns FAR procedure address 
DosLoadModule X Loads a dynamic link module 
DosGetMachineMode X Returns current CPU mode 
BadDynLink X Error on dynamic link 
Device Monitors 
DosMonClose X Terminates character device 
monitoring 
DosMonOpen X Accesses a character device 
DosMonRead X Moves data 
DosMonReg X Establishes I/O buffer 
DosMonWrite X Writes to the monitor's buffer 
Session Management 
DosStartSession X Starts a session 
DosStopSession X Stops a session 
DosSelectSession X Allows a parent to switch to a 
child 
DosSetSession X Sets child session status 
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TABLE 1.2 (Continued) 


Name API FAPI Description 


Device I/O Services 


DosBeep X Beeps speaker 
DosCLIAccess X Requests privilege for enabling/ 
disabling interrupts 
DosDevContfig X Gets information about attached 
devices 
DosDevIOCtL X Sets up control functions for a 
specified device 
DosGetPID X Returns current process [D 
DosPFSActivate X Specifies the code page and foot 
to make active 
DosPFSCloseUser X Indicates the spool file is closed 
DosPFSInit X Allows initialization of the code 
page and font 
DosPFSQueryAct X Queries the active code page and 
font 
DosPFSVerifyFont X Indicates validity for the 
specified code page and font 
DosPhysicalDisk X Obtains disk information 
DosPortAccess X Requests or releases port I/O 
privilege 
DosSendSignal 4 Sends a Ctl/c or Ctl-Break to 
process 
KbdDeRegister X Deregisters a keyboard 
KbdCharIn X Reads a character 
KbdClose X Ends the existing logical keyboard 
KbdFlushBuffer X Clears the keyboard buffer 
KbdFreeFocus X Frees the logical to physical 
keyboard bond 
KbdGetCp X Allows access to the current 
code page 
KbdGetFocus X Binds the logical to physical 
keyboard 
KbdGetStatus X Gets the state of the keyboard 
KbdOpen X Creates a new logical keyboard 
KbdPeek X Returns the last character without 
clearing the keyboard buffer 
KbdRegister X Registers a keyboard 
KbdSetCp X Sets the code page 
KbdSetCustxt X Installs a code page and calling 


handle 


TABLE 1.2 (Continued) 


Name 
KbdSetFgnd 


KbdSetStatus 
KbdStringIn 
KbdSynch 


KbdXlate 
MouClose 
MouDeRegister 
MouDrawPtr 


MouFlushQue 
MouGetDevStatus 


MouGetEventMask 
MouGetNumButtons 


MouGetNumMickeys 
MouGetNumQueEl 
MouGetPtrPos 


MouGetPtrShape 
MouGetScaleFact 


MoulnitReal 
MouOpen 
MouReadEventQue 


MouRegister 
MouRemoves Ptr 


MouSetDevStatus 
MouSetEventMask 
MouSetPtrPos 


MouSetPtrShape 
MouSetScaleFact 


MouSynch 
VioDeRegister 
VioEndPopUp 


API 


x KX K XK 


FAPI 
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Chap. 1 


Description 


Raises the priority of the 
foreground keyboard’s thread 


Sets the keyboard characteristics 
Reads a character string 


Synchronizes access for a 
keyboard to device driver 
Translates scan codes to ASCII 


Closes the mouse driver 
Deregisters a mouse device 


Opens a mouse pointer image to 
the mouse 


Empties the mouse queue 


Returns status flags for the mouse 
driver 


Returns event mask for mouse 


Returns number mouse buttons 
Supported 


Returns number of mouse 
movement units per centimeter 


Returns status for mouse device 
drive event queue 


Gets row and column position of 
mouse 


Gets the pointer shape 


Gets the scaling factors for the 
mouse 


Initializes the DOS mode mouse 
Opens the mouse device 


Reads an event from the mouse 
device event queue 


Registers a mouse 


Clears a pointer area from mouse 
use 


Sets mouse status 
Assigns a new event mask 


Resets the row and column 
position for the mouse 


Sets the mouse shape 


Assigns the mouse a new pair of 
scaling factors 


Synchronizes the mouse 
Deregisters a video subsystem 
Closes a temporary screen 
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TABLE 1.2 (Continued) 


Name 


VioGetAnsi 


VioGetBuf 


VioGetCp 
VioGetConfig 
VioGetCurPos 
VioGetCurType 


VioGetFont 
VioGetMode 


VioGetPhysBuf 


VioGetState 
VioModeUndo 
VioModeWait 


VioPopUp 
VioPrtSc 
VioPrtScToggle 
VioReadCellStr 


VioReadCharStr 


VioRegister 


VioSaveRedraw Undo 
VioSavRedraw Wait 


VioScrLock 
VioScrollDn 
VioScrollUp 
VioScrollLf 
VioScrollRt 
VioScrUnLock 
VioSetAnsi 


VioSetCp 
VioSetCurPos 
VioSetCurType 
VioSetFont 
VioSetMode 
VioSetState 


FAPI 


x KK KK XK 


x KK KK K 


x Kx KK XK 
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Description 


Returns the current ANSI 
ON/OFF state 

Returns the address of the logical 
video buffer 


Allows a query of the code page 
Returns the display configuration 
Returns the cursor position 
Returns the cursor type 


Returns font 
Returns display mode 


Gets addressability to physical 
display buffer 


Gets display state 
Changes mode 


Allows notification when display 
must be restored 


Allocates a temporary screen 
Copies the screen to printer 
Called when Ctrd-PrtSc is entered 


Reads character-attribute pairs 
(cells) from screen 

Reads a character string from the 
display 

Registers an Alternate Video 
subsystem 

Cancels a VioSavRedrawWait 


Notifies a redraw must be 
performed 


Locks the physical display 
Scrolls down 

Scrolls up 

Scrolls left 

Scrolls right 

Unlocks the physical display 


Activates or deactivates ANSI 
support 


Sets the code page 

Sets the cursor position 
Sets the cursor type 
Downloads a display font 
Sets display mode 

Sets the display state 
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TABLE 1.2 


Name 


VioShowBuf 


VioWrtCellStr 


VioWrtCharStr 


VioWrtCharStrAtt 


VioWrtNAtt 


VioWrtNCell 


VioWrtNChar 


ViowrtT Ty 


File I/O 


DosBufReset 


DosChDir 
DosChgFilePtr 
DosClose 
DosDelete 
DosDupHandle 


DosFileLocks 


DosFindClose 


DosFindFirst 
DosFindNext 


DosMkDir 
DosMove 
DosNewSize 
DosOpen 
DosQCurDir 


DosQCurDisk 


DosQFHandState 


(Continued) 


FAPI 


x KK K XK 


x KK KK 


x x 
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Description 


Updates the physical display with 
the logical 

Writes a string of character- 
attribute cells to display 

Writes a character string to the 
display 

Writes a repeated attribute string 
to the display 

Writes an attribute M times to 
the display 

Writes a cell M times to the 
display 

Writes a character M times to 
the display 


Writes a character string to the 
display 


Flushes a requesting process 
cache buffer 


Defines the current directory 

Moves the read/write pointer 

Closes a file handle 

Removes a directory entry 

Returns a new file handle for an 
open file 

Locks and unlocks a range in an 
open file 

Closes the association between 


directory handles and search 
functions 


Finds the first set of names that 
match a directory specification 


Locates the next set of matching 
directory entries 


Creates specifies directory 
Moves a file 

Changes a file size 

Opens a file 


Gets full path name for current 
directory 


Gets the current default drive 


Queries the state of the specified 
files 
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TABLE 1.2 (Continued) 


Name API FAPI Description 

DosQFileInfo X Returns information for a specific 
file 

DosQFsInfo X Queries information from a file 
system device 

DosQHandType X Determines whether a handle 
references file/device 

DosQVerify X Returns the value of the verify 
flag 

DosRead X Reads from a file to a buffer 

DosReadAsync X Transfers from a file to a buffer, 
asynchronously 

DosRunDir X Removes a subdirectory 

DosScanEnv X Searches an environment for a 
value 

DosSearchPath X Searches a path for a filename 

DosSelectDisk X Specifies the default drive 

DosSetFHandState X Sets the state of a file 

DosSetFileInfo X Specifies information for a file 

DosSetFileMode X Changes the attributes of a file 

DosSetFsInfo Xx Specifies information for a file 
system device 

DosSetMaxFH X Defines a maximum number of 
file handles 

DosSetVerify X Sets a verify switch 

DosWrite X Transfers from a buffer to a file 

DosWriteAsync X Transfers from a buffer to a file, 


Errors and Exceptions 


DosErrClass 
DosError 


DosSetVac 


Messages 


DosGetMessage 


DosInsMessage 
DosPutMessage 


Trace/Program Startup 


DosGetEnv 


asynchronously 


Returns error code options 


Allows the disabling or user 
notification on errors 


Allows address registration for 
machine exceptions 


Retrieves a message from a 
message file 


Inserts text into message body 
Outputs a message 


Returns a pointer to the 
environment string 
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TABLE 1.2 (Concluded) 


Name API FAPI Description 


DosGetVersion X Returns the OS/2 version number 


Code Page Support 


DosGetCp X Gets the current code page 
DosSetCp X Sets the current code page 
DosSetProcCp X Sets the current code page 


Country Support 


DosCaseMap X Case maps country codes to a 
binary string 

DosGetCollate X Obtains country information 

DosGetCtryInfo X Obtains country information 

DosGetDBCSEv X Obtains country environment 
vector 


Most microcomputer system software involves intersegment references between 
segments contained in the program file obtained from the linker, the .EXE file in 
DOS. This reference mechanism 1s referred to as static linking because it is imple- 
mented prior to run-time loading. Loading merely brings the segments into mem- 
ory and modifies fix-up points to reflect the correct intersegment references. 

OS/2 allows the loader (not the linker) to reference segments included in spe- 
cial dynamic-link libraries (DLL). The entire APT is based on DLL programming. 
How does a dynamic-link reference function? Basically, any program can reference 
DLL routines by indicating that they are externally defined (using the EXTRN 
pseudo-op, for example, in an assembler program). At link time the system matches 
external references with other object modules (.OBJ files) and libraries (.LIB files) 
specified. Since the DLL routines are an .EXE file and suitable for run-time load- 
ing, they do not fall in the OBJ or .LIB category. A new type of library file is 
required, the dynamic-link definition library file. This file simply satisfies the exter- 
nal reference by indicating to the loader the location of the DLL routine involved. 
At run time the loader then adds the DLL code from storage to the executable 
module. 

The API call interface employs dynamic linking. The major advantages to this 
approach are that: 


1. The API code can easily be modified at the system level 


2. The API call can be satisfied with in-line code instead of the DLL code if 
desired by proper loading 


3. The API can include some services not essential to kernel-level privilege, and 
these services can be implemented with less protection 


4. The API call is direct, not via vector table routing 
5. The API library can easily be expanded 
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In Chapter 2 we begin to develop the programming techniques needed to access 
properly the services outlined in Table 1.2. 


1.2.3 Memory Management 


OS/2 provides a significant memory management capability by using the hardware 
features of the 80286, together with its system architecture. OS/2 provides the capa- 
bility to move segments around and free memory in response to DLL requirements. 
Also, using the P bit of the descriptor, OS/2 can determine when a referenced 
segment is needed and dynamically roll these segments in or out of memory from 
extended storage, in response to program execution. Such segment swapping is the 
basis for allowing large-scale access to the virtual address space in a given physi- 
cal memory implementation. Provision exists to: 


1. Create or close new segments 
2. Create or close huge segments (greater than 64 KB) 
3. Suballocate segments 


This corresponds to the demand loading philosophy, which OS/2 supports, and 
allows dynamic reallocation and subdivision of memory in response to changing 
requirements. 


1.2.4 Multitasking 


Just as memory management has been addressed earlier in the chapter, multitasking 
has been covered in Sections 1.1 and 1.2.1. We have mentioned the notion of 
threads (a dispatchable unit), processes (a collection of threads and system re- 
sources), and a session is a collection of processes run in a virtual context. Under 
OS/2, for example, a given element of program code comprises a thread’s executable 
context. This may run as multiple instances in which multiple copies of the thread 
are executed as individual tasks, each task running the same code. Based on this 
interpretation the meaning of an instance is clear: an executing entity dynamically 
different from all others. 

The reentrant nature of OS/2 threads requires that if multiple threads access the 
same data block, the threads must synchronize access to this data. This synchroni- 
zation can be accomplished using a number of OS/2 features already discussed 
(semaphores, queues, pipes, flags, and shared memory). Interprocess communication 
requires the use of these facilities, and threads desiring to access such common data 
blocks must serialize their access. In general, when no common access between 
processes is required, OS/2 will asynchronously execute the processes in a multi- 
tasking situation. 

A simple example of process synchronization is presented in Chapter 2, where 
a common data area (shared segment) is established using DosAllocShrSeg and the 
first few bytes are used to establish a handshake. The creating process sets the flag 
byte to zero and turns on the child process, which also has access to the segment. 
Once the child process completes its generation of data (to be used by the parent), 
it sets the flag to 1. The parent, sensing a 1, then accesses the segment. 
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Semaphores, pipes, and queues have much the same functional behavior ex- 
cept that they represent tools specifically designed for interprocess exchanges. These 
OS/2 objects represent a formal extension of interprocess communications (compared 
with the shared memory flag above, for example). DosSetSigHandler and 
DosFlagProcess are examples of formal flag implementation services. We examine 
those resources in later chapters. 

Processes are created with the API service DosExecPgrm, as we shall see in 
Chapter 2. They are hierarchical in that the creating process serves as the parent, 
with the created process the child. The API DosKillProcess can be used to terminate 
a child process. At creation a process can be established asynchronously, during 
which the parent continues to execute in normal time-slice fashion, or synchro- 
nously, where the parent is suspended until the child completes execution. When a 
thread is created it assumes the priority level of its creator. Using DosSleep a thread 
may stop execution for a fixed period. During this period the thread is not allowed 
to access system resources. 

We have considered dynamic linking, in which a DLL is created and an asso- 
ciated definition file containing pointers to the DLL entries. At run time the defini- 
tion file has already been linked with the main calling routine, so the loader simply 
brings the DLL into memory and completes its entry-point fix up. A second type of 
dynamic linking exists called run-time dynamic linking. In the latter procedure the 
API DosLoadModule can actually be used to load a DLL after execution begins. 
The difference between run-time dynamic linking and load-time dynamic linking is 
that loading the DLLs and entry point fix-ups can occur after execution begins in 
the former if needed, whereas they must occur during loading in the latter. 

Finally, we look briefly at input and output (I/O) in the privileged multitask- 
ing environment. I/O occurs from level 2, whereas applications execute from 
level 3; hence OS/2 must build a call gate for access to segments that accomplish 
I/O— I/O-protected segments (LOPS). Such segments are created by the loader, and 
typically, API calls such as DosOpen or DosClose establish generation of an IOPS 
(see Table 1.2). 


1.2.5 Version 1.0 and 1.1 Differences 


Earlier we saw the API functions described (Table 1.2). In the IBM OS/2 Standard 
Edition 1.0 these functions comprised the bulk of the services afforded by OS/2 and 
were intended for use by programmers desiring to access these services. The Toolkit 
routines (reference 7) provide a collection of include files (for both C and assem- 
bler) that make use of the API services relatively easy. 

With the development of Standard Edition 1.1 (aside from some relatively 
minor enhancements) the addition of the Presentation Manager (PM) graphical inter- 
face, and its associated 300 plus function library, is the major improvement over 
Version 1.0. Essentially, OS/2 under Version 1.0 employs a DOS-like full-screen 
command mode for the user interface. This display mode is capable of addressing 
only one screen at a time. Under the PM a Windows-like interface is presented and 
each executing context can be visualized simultaneously as part of a sequence of 
windows occupying the screen. 
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It is programming of the OS/2 PM that constitutes the major enhancement of 
Version 1.1. This programming employs techniques similar to those outlined in the 
Windows Software Development Kit (SDK) [26-28] for development of Windows 
programs. 


1.3 THE OS/2 PRESENTATION MANAGER 


It is worthwhile to look briefly at the Presentation Manager (PM) to get a feeling for 
how this type of interface is implemented. The PM runs as an executive subset 
under OS/2. IBM has developed the Systems Application Architecture (SAA) and 
the PM implements the Common Programming Interface (CPI) component of SAA, 
which makes portability to other SAA-supported environments (such as VM and 
MVS on the System/370 and Operating System/400 on the Application System/400) 
relatively straightforward. 

Communications and network-intensive applications are not generally amenable 
to the SAA without additional software support. The Extended Edition Version 1.1, 
for example, is intended for these more uniquely hardware-specific applications. 
Examples include airline reservation systems, bank transaction processing, some 
large-scale process control applications, real-time processing, and communications 
front-end (physical layer) processing. 

The PM interacts with the OS/2 user via a graphical user interface [30-35]. By 
graphical user interface we mean the screen appearance when the PM is invoked. 
This display is illustrated in Figure 1.7 with a typical pulldown menu. The maxi- 
mize/minimize buttons can be used to reduce the contents of the client area to an 
icon. This icon can be restored using the mouse. The client area contains the visible 
portion of the display context, which presents the active window interface. It is here 
that the executing program displays its particular graphical context. The PM allows 


Title Bar 


System Menu Icon 


——— Window Title 


b 


Figure 1.7 The Presentation Manager standard window. 
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the client area to be subdivided into tiled (windows adjacent to each other) or 
overlapped (windows lying on top of each other with varying offsets) windows. This 
facilitates a partial display of the contents of several windows simultaneously. 

In addition to the features illustrated in Figure 1.7, the programmer can call up 
modal and modaless dialog boxes and message boxes. These can be used to achieve 
I/O in the PM context. A modal dialog box retains control of the execution until it 
is destroyed (usually by clicking the mouse over a termination panel). A modaless 
dialog box allows the PM to permit windows in other applications to be activated 
after it has been created. A message box is a predefined dialog window available to 
all applications for displaying text and receiving user I/O. 

The PM has a strong graphics capability (as differentiated from graphical 
interface) with which computer-generated graphics may be displayed in the client 
area. This Graphics Program Interface (GPI) employs API calls beginning with Gpi. 
The PM also has a clipboard that can be used to hold intermediate data and re- 
sources (such as metafiles and bitmaps). A metafile defines the contents of a win- 
dowed picture so that it can be used by other applications. These metafiles are 
created using GPI calls and conform to the Mixed Object Document Content Archi- 
tecture (MODCA) interchange standard. A bitmap, on the other hand, is a represen- 
tation in memory of data displayed on an all-points-addressable basis and requires 
that the object in question be capable of being specified in this mode. 

Finally, the programming for the interface itself employs a number of new 
library elements. The PM executive is a dynamic program that is constantly access- 
ing each application context for changes and conversing with the application via a 
stream of messages. When an application executes various window functions, for 
example, the function causes specific messages to be sent to the PM executive. 
These are then interpreted and the executive generates a response. 

The general PM program flow of activity is illustrated in Figure 1.8, where 
termination of the window is accomplished by the executive in response to a 
WM_QUIT message. This flowchart shows the setup code as distinct from the 
message-processing loop, as it is. C is the language of choice for programming the 
PM executive. 

Conventional C programs have a basic template that appears as 


Preprocessor 
main() 


af 
{ 
functionl() 
} 
} 


functionN( ) 


{ 


{ 
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BEGIN 
= 
INITIALIZE 
WINDOW 
NORMAL 
SETUP 
GET 
MESSAGE 
Ss 
TRANSLATE TERMINATE 
MESSAGE WINDOW 
SEND TO EXIT 
WINDOW 
PROCESS 
WINDOW Figure 1.8 Dynamic picture of a 


Windows application, similar to the PM 
implementation. 


Each function is callable internal to either main ( ) or another (group of) function(s). 
A simple PM program with one window might have a template of the following 
form: 
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Preprocessor 
void cdecl main(argc,argv) 
{ 
-code to initialize window 
-loop to continuously read messages sent from the executive 


} 
“window function 
‘ 
-this function directs execution to appropriate PM func- 
tions based on “message” input from the PM executive 
} 
“initialization functions” 
{ 


-functions needed to initialize the first, additional, and 
every instance of a window 


} 


other needed user-defined functions 


oe°o 


Figure 1.9 illustrates a Structure Chart for the upper hierarchical levels of a PM 
application. This chart is generic in the sense that it only indicates entities that are 
common to all PM programs. The reader familiar with the Microsoft Windows 
executive will see a close parallel between programming for this executive and 
programming the PM executive [29]. 
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Figure 1.9 Generic Structure Chart for the upper hierarchical levels of a 
Presentation Manager application. 
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1.4 SUMMARY 


In this chapter we have introduced the IBM Operating System/2 in the framework 
of the Intel 80286 and 80386 CPUs. Initially, the CPU registers were described and 
the Protected Mode address space examined. The Protected Mode provides a frame- 
work from which to perform memory management and multitasking because of the 
hardware interlocks into segment management. Basically, the access rights control 
byte in the segment address translation register word determines what data and con- 
trol segments will have access to a given memory location. 

This segment control, then, is the mechanism by which the hardware delimits 
Protected Mode access. This is applied to the software via the operating system (and 
the local descriptor tables (LDTs) and the global descriptor table (GDT)). OS/2 
provides system services similar to the BIOS and DOS interrupt services via the 
family Applications Programming Interface (FAPI). The FAPI is a subset of the 
more complete API functions, which represent a complete set of Protected Mode 
services. Representative of these services are the following categories 


1. Mouse (Mou) 
Video (Vio) 
DOS (Dos) 
Graphical (Gpi) 
Spool (Spl) 
Device (Dev) 
Keyboard (Kbd) 
8. Window (Win) 


aA es SP 


The API calls, then, allow access to system hardware and file services under OS/2. 
OS/2 has provision to add devices to the system by creation of additional device 
drivers and input/output privilege level (IOPL) is assisted using the Dev and Dos 
Services. 

The Presentation Manager (PM) represents the Version 1.1 user-friendly graph- 
ical interface for OS/2. Under Version 1.1 the user also has a choice of the full- 
screen command prompt interface mode which is that employed by Version 1.0. The 
PM display is similar to that used by Microsoft Windows Version 2.0 and provides 
for overlapped (or tiled) window presentation of active process information in a 
multitasking environment. The PM executive interacts dynamically with the execut- 
ing programs. Associated with the PM are a large class of functions (window func- 
tions) used to regulate the interface under program control. The messages exchanged 
between the PM executive and the program are continuous and dynamically varying. 
Hence this executive provides a time-varying interactive display that can be updated 
and controlled using the mouse. It is very similar to the interface provided by the 
Apple MacIntosh operating system. 
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PROBLEMS 


In Real Address Mode assume a CS register value of 07F8H and an IP register value 
of 274AH. What is the 20-bit physical address? 


Does the fact that OS/2 is a multitasking operating system imply that it is a multi- 
processor operating system, as well? 

What is the largest fixed-point value that the 80386 can accommodate? Largest signed 
fixed-point value? 


The exit processing for OS/2 is via a call to DOSEXIT rather than a RET instruction. 
If the requisite processing for DOSEXIT is 


EXTRN DosExit:FAR 
PUSH WORD ActionCode ;Indicates end thread or process 


PUSH WORD ResultCode ;Result Code 
CALL DosExit 
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define a macro 
@DosExit action, result 


that can be used to setup and execute the exit operation. 


The video screen unlock processing for OS/2 is via a call to VIOSCRUNLOCK. As- 
suming that the requisite processing for this call is 


EXTRN VioScrUnLock:FAR 


PUSH WORD VioHandle ;Video handle 
CALL VioScrUnLock 


define a macro 
@VioScrUnLock viohdl 


that can be used to setup and execute the unlock operation. 


The video screen lock processing for OS/2 is via a call to VIOSCRLOCK. Assuming 
that the requisite processing for this call is 


EXTRN VioScrLock:FAR 

PUSH WORD WaitFlag ;Block or not 

PUSH BYTE Status ;Lock status returned (address) 
PUSH WORD VioHandle ;Video handle 

CALL VioScrLock 


where PUSH@ means to push an address on the stack, define a macro 
@VioScrLock waitf,iostat,viohdl 


that can be used to setup and execute the lock operation. 

What are the three principal features that the OS/2 Standard Edition contributes over 
conventional DOS operating system characteristics? 

While 80286 code (source) will run on 80386 systems, why will 80386 applications 
code generally not run on 80286 systems? 

In the IBM PC AT, 16 levels of hardware interrupts are available to the system user. 
How many 8259As are required to support this number of interrupt levels? 

The DOS partition in the IBM microcomputer environment supports the first 1 MB of 
addressable memory. Why do most early systems allow a maximum of only 640 KB 
of program memory access? Where does OS/2 extended memory reside? 

What is the difference between physical and virtual memory, and how is virtual 
memory managed? 

How does OS/2 differentiate system memory space from applications memory space? 
How much virtual memory space is accessible by applications? 

Why would data communications processing not reside at level 0 to ensure that no 
data is lost during a communications session? 
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1.14 
1.15 


1.16 
1.17 


1.18 


1.19 


1.20 


1.21 


How does the 80286 CPU know that the system is to operate in Protected Mode? 
When writing a device driver, mixed-language programming is probably an optimum 
approach. Assuming that a driver is written using a combination of C and assembly 
language, what parts are likely candidates for assembler code? What parts are likely 
candidates for C code? 

Explain the major difference between a pipe and a queue. 

Would you say that the API implementation represents a favorable step for assembly 
language programming of OS/2? For C programming of OS/2? Explain. 

If two threads from the same process need to access a common data area, will they 
run synchronously or asynchronously? If the threads are from different processes, will 
they access in synchronous or asynchronous fashion? 

What is the thread equivalent to DosKillProcess? How does it differ from the activity 
for a process? 

Can we use the Gpi services with full-screen command mode to generate screen 
graphics under CGA, for example? 

Which is preferred in a multitasking environment: modal or modaless dialog box 
implementation? 


PART II 
Programming OS/2 Using Assembler 


2 Introductory OS/2 
Assembler Programming 


OS/2 is a unique program environment devoid of the normal interrupt calls found in 
conventional assembly language programs. In their place OS/2 implements Applica- 
tion Program Interface (API) function calls, which provide the programmer with ac- 
cess to system services. Specific services include the familiar DOS BIOS and 
INT21H function calls, an enhanced set of video display handlers, mouse services, 
and keyboard handlers. These are the most obvious extensions of OS/2, and they 
permit the user a vastly increased capability to develop multitasking modules and 
extend program usage beyond the normal 64K segment limit. 

In this chapter we examine assembly language programming in the context of 
OS/2 [1,2]. The goal of the exposition is to provide the reader with examples of the 
usage of assembly language in the OS/2 framework. This is not a treatise on how to 
program assembler; rather, we hope to achieve an understanding of the OS/2 inter- 
face. 


2.1 OS/2 SERVICES: ACCESSING THE API 


A great deal of the new programming emphasis using OS/2 is the API services 
which are contained in the IBM (or Microsoft) supplied library, API.LIB. The serv- 
ices contained in API.LIB can be accessed through uppercase specification of the 
service name preceded by proper setup of parameter information appropriate to the 
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function in question. Unlike the DOS and BIOS interrupt routines, which pass 
parameter information using the general-purpose registers, the OS/2 API procedures 
receive parameters via the stack, which must be installed by the user. This is in 
much the same fashion as the passing of parameters to functions or subroutines in 
a higher-level language (HLL). 

To understand how this works consider the video API call, which returns the 
cursor position to two stack locations. This routine, VioGetCurPos, has the follow- 
ing calling sequence for the service [3]: 


1. Define VioGetCurPos as EXTRN and FAR 
2. PUSH a 32-bit address for 


row (word) 
column (word) 


on the stack, respectively 
3. PUSH a device handle 


VioHandle (word) 


on the stack 
4. CALL VioGetCurPos 


In this example the routine VioGetCurPos is treated in mixed upper and lower case 
for readability. The actual OS/2 library reference is upper case: 


VIOGETCURPOS 


To continue to use the more readable mixed-case references, which are in the style 
of the IBM references, the programmer must consider what is available or can be 
developed to facilitate the use of these mixed-case calls. Fortunately, IBM provides 
several include files (with extension .inc) for use with the assembler that set up 
macros for using the API library. This setup includes loading the stack with the 
proper parameters needed by the API service routine. OS/2 has two include files, 
doscalls.inc and subcalls.inc, that properly develop macros to be called for API 
service. These two files are loaded using a third file, sysmac.inc, which simply 
installs doscalls and subcalls as macro libraries: 


IF 1 
include sysmac.inc 
ENDIF 


The file doscalls.inc contains macros for calling all the Dos...calls. The file 
subcalls.inc contains macros for calling all kbd..., Mou..., and Vio... calls. 
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Returning to VioGetCurPos, consider the subcalls macro used to set up and 
call this service routine: 


@VioGetCurPos macro row, column, handle 
@define VIOGETCURPOS 
@pushs row 
@pushs column 
@pushw handle 
eall far ptr VIOGETCURPOS 
endm 


We see immediately that this macro calls three other macros: @define, @pushs, and 
@pushw. These macros are defined as follows: 


@define macro callname 
ifndef callname 
extrn callname:far 
endif 
endm 

@pushs macro parm 
-errb <parm> 
mov ax,SEG parm 
push ax 
lea ax,parm 
push ax 
endm 

@pushw macro parm 
Mov ax,parm 
push ax 
endm 


Clearly, @define is used to get VIOGETCURPOS as an externally defined 
FAR procedure (it appears in API.LIB). The macro @pushs pushes a 32-bit address 
for the dummy parameter, parm, onto the stack and @pushw pushes parm itself onto 
the stack. The calling sequence for @VioGetCurPos sets up row and column to 
receive the cursor position values after the final FAR call to VIOGETCURPOS. 

This is how the OS/2 API services are accessed using assembly language and 
the doscalls.inc, subcalls.inc, and sysmac.inc files. In this chapter we use only a 
small subset of the API calls. These services are indicated in Table 2.1. Generally, 
the focus of interest in this chapter is on the printer, keyboard interrupt, and screen 
buffer, as the API calls of Table 2.1 indicate. 

OS/2 reserves the right to redefine memory dynamically during program exe- 
cution. This is necessary to implement multitasking and memory management of 
huge segments (greater than 64K segments). Since OS/2 can access 16 Megabytes 
(MB) of actual memory because of the 24-bit physical address size, it must map the 
full virtual program memory into this space, or smaller, during program execution. 
The virtual memory access may contain up to a full gigabyte (2*° bytes) of individu- 
ally addressable byte locations. 
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Clearly, physical address space is normally difficult to access and naturally 
remains the province of OS/2. In some cases, however, the programmer has access 
to this dimension. We will see a situation of actually writing to the OS/2 physical 
memory when the screen buffer 


TABLE 2.1. API SUBSET USED IN CHAPTER 2 


API function Comment 
DosOpen Open specified device or file 
DosExit Terminates active threads and processes 
DosWrite Transfers the specified bytes from a buffer to the specified file 
DosClose Closes the specified device or file 
VioScrollUp Scrolls the screen upward 
VioSetMode Sets the graphics or alphanumeric screen mode 
VioScrLock Locks the physical display buffer context 
VioGetPhysBuf Retrieves a segment selector for the physical display buffer 
VioScrUnLock Unlocks the physical display buffer context 
KbdStringIn Loads a keyboard buffer with a character string 


is accessed in a subsequent example. It is possible to gain access to the screen 
buffer by locking the screen context and then using a segment selector returned by 
OS/2 for writing directly to the physical buffer containing the screen addresses. This 
differentiates the IBM physical screen buffer, with its fixed physical locations in 
memory, from other RAM addresses, which can vary in dynamic but protected fash- 
ions under OS/2. 


2.2 INTRODUCTORY ASSEMBLER PROGRAMMING 


As indicated earlier, we have assumed that the reader has a background in both 
80286 assembler and the C language. This book does not teach either, but we do 
provide a brief review of the syntax associated with the languages. In this section 
we examine the macro assembler that is compatible with the Protected Mode. 
Appendix A contains the Macro Assembler/2 instructions and pseudo-ops. 


2.2.1 The IBM Macro Assembler/2 


There are two reasons why programmers should be interested in assembly languages. 
First, assembler provides an understanding about both the underlying software archi- 
tecture for a given microprocessor and the needed chip interfaces for a given micro- 
computer. Second, situations can arise where other languages are inadequate for 
achieving optimized performances. The Macro Assembler/2 has basically the same 
features as other Intel assemblers. The dominant active instruments in the assembler 
are the instructions with the form 
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[label] instruction-mneumonic [operand(s) ] [ ;comment] 


Here the brackets indicate that the quantities contained within are optional depend- 
ing on instruction type. The instruction sequence 


mov cx,1000 sload loop limit 


mov si,O einitialize index 

DO11: ;label for loop 
Mov ax,Ssi sload ax with index 
sub ax,100 ssubtract 100 from index 
cmp ax,0 scheck to see if zero 
je ELSE1 sjump if zero to ELSE1 
inc si eincrement index 
loop DOl11 ;loop back to DOl11 


ELSE1: 


is an example of the use of the move(mov), subtraction(sub), jump-if-equal(je), 
increment(inc), compare(cmp), and loop instructions. Note that the labels DO11 and 
ELSE1 go with the next line of code. In this fragment the loop instruction decre- 
ments cx each time. When ax becomes zero the jump takes place to the target label 
ELSE1. This very brief illustration of the assembler instruction usage is intended as 
an example of the IBM Macro Assembler/2, MASM. For a complete discussion of 
the assembler instructions, consult the Language Reference Manual [4]. 

In addition to the instructions the assembler has a class of statements that 
provide information about the program environment. These statements do not result 
in machine code and are referred to as pseudo-ops. Typical of the pseudo-ops is the 
SEGMENT directive, which is used to demarcate the various segment definitions 
within the source code. The SEGMENT pseudo-op has the form 


sequence SEGMENT align-type combine-type ‘class’ 


where segname is the name of the segment. Align-type indicates how the segment 
begins in memory [PARA: paragraph boundary [address divisible by 16]; BYTE; 
WORD; or PAGE: last 8 bits of address are zero], and combine-type indicates how 
the segment is to be linked [PUBLIC: all public segments with the same name are 
linked; COMMON: all segments with the same name overlap; AT(exp): segment 
located at nearest paragraph to “exp”; STACK: stack segment; and MEMORY: 
higher addresses than other segments]. The designator ‘class’ refers to a collection 
of segments with the same class name. Segments end with 


segname ENDS 


To define segment type the ASSUME pseudo-op is used to associate a name 
with a segment register: 


ASSUME CS:segname, SS:segname[,DS:segname[,ES:segment] ] 
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Here CS is required and SS is required when a stack segment is present. Both DS 
and ES are optional. We could continue to enumerate the Macro Assembler features; 
however, the best technique for elucidating the language is through illustration. In 
the following section we consider such an example. 


2.2.2 An Example Program: Printer Control 


Figure 2.1 contains an assembler program that causes the printer to print in graph- 
ics mode under OS/2. The program opens with two pseudo-ops: PAGE and TITLE. 
PAGE has the form 


PAGE operand1,operand2 


The entry in operand] indicates the number of horizontal lines per page in the as- 
sembler listing (here it is 55). Operand2 is the number of characters per line in the 
listing. The TITLE pseudo-op specifies the title on the first line of each assembler 
listing page. Spread throughout the program are semicolons. All text following a 
semicolon on the same line is treated as a comment. The pseudo-op IF1 (a condi- 
tional pseudo-op) indicates that all instructions and pseudo-ops following it and prior 
to the next ENDIF are to be implemented during pass 1 of the assembler. In Figure 
2.1 the file sysmac.inc is to be included at this point. 

Sysmac causes doscalls.inc and subcalls.inc to be included which set up 
macros for all API calls that appear in the subsequent code segments. The pseudo- 
op .sall causes macro listings to be suppressed. Next follows the GROUP pseudo-op. 
This pseudo-op collects the data segment under the name dgroup: 


dgroup GROUP data 
The stack segment follows. Here 256 copies of the string 
STACK... 


are used to form the stack segment. This should be more than adequate for the stack 
size required by most small programs. The pseudo-op, db, stands for define byte and 
the dup operator duplicates the 8-byte string within parentheses. 

The data segment follows and requires some explanation in conjunction with 
the API calls that are in the code segment. Consider first the variables defined in 
this data segment that begin dev_... . There are eight of these variables and they are 
defined in reference to the @DosOpen API macro call. Consider the form of this 
call in the code segment 


@DosOpen dev_name,dev_hand,dev_act,dev_ size, 
dev_attr,dev_flag,dev_mode,dev_rsv 


This API call opens a file with file path name dev_name. The path is the zero-ter- 
minated string: ‘LPT1’,0. The file handle is returned with dev_hand. The action 
taken is returned in dev_act, where 
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PAGE 55,132 
TITLE PRT2 - This is the initial printer routine (PRT2.ASM) 


DESCRIPTION: This program simply prints a "74" in 
graphics mode (320 times) for two lines which are 
meshed together. 


include sysmac.inc 


-sall ;Suppresses macro lists 
dgroup GROUP data 


STACK SEGMENT PARA STACK 'STACK'! 
db 256 dup('STACK ') 

STACK ENDS 

DATA SEGMENT PARA PUBLIC 'DATA! 


in_buffer db 400 dup(0) 


in_leng dw $ - offset in_buffer 

bytesin dw 320 

bytesout dw fe) 

in_bufferl db 1BH,4BH,64D,01H ;320 columns 
bytesinl dw 4 

in_buffer2 db ODH, OAH 

bytesin2 dw 2 

in_buffer3 db 1BH, 41H, 08H 

bytesin3 dw 3 


in_buffer4 db 1BH, 32H 


° 
’ 


dev_name db ‘LPT 0 
dev_hand dw 0 
dev_act dw 0 
dev_size dd 0 
dev_attr dw 0 
dev_flag dw 00000001b ;Open File 
dev_mode dw 0000000011000001b ;Hdl private,deny none,w/o 
dev_rsv dd 0 
DATA ENDS 
t 
CSEG SEGMENT PARA PUBLIC 'CODE' 
ASSUME CS:CSEG,DS:DATA,ES:DATA,SS:STACK 
PRTSC1 PROC FAR 
push ds 
pop es 


;Open LPT1 as device 
@DosOpen dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag,dev_mode,dev_rsv 
cmp ax,0 
je ELSE1 
7;Exit 
@DosExit 1,0 


mov cx,320 7320 columns 
mov si,O sinitialize index 


mov al,74 spins 2,4,5, and 7 

mov in_buffer[si],al ;load printer write buffer 

inc si ;increment buffer index 
loop LOOP1 


;Set lptl vertical spacing 


Figure 2.1 Assembler program prt2.asm, which prints printer graphics under 
OS/2 Protected Mode. 
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@DosWrite dev_hand,in_buffer3,bytesin3,bytesout 

;Activate spacing 
@DosWrite dev_hand,in_buffer4,bytesin2,bytesout 

;Initialize printer graphics 
@DosWrite dev_hand,in_bufferl,bytesin1,bytesout 

;Write print buffer 
@DosWrite dev_hand,in_buffer,bytesin,bytesout 

7;CR & LF 
@DosWrite dev_hand,in_buffer2,bytesin2,bytesout 

;Reset graphics mode 


@DosWrite dev_hand,in_bufferl,bytesin1,bytesout 

;Write print buffer again 
@DosWrite dev_hand,in_buffer,bytesin, bytesout 

;Close device 


@€DosClose dev_hand 
7Exit 
@DosExit 1,0 
PRTSC1 endp 
CSEG ends 
end PRTSC1 


Figure 2.1 (Concluded) 


0001H = file exists 
0002H = file created 
0003H = file replaced 


Here the file’s size in bytes is returned in dev_size. The file attribute bits are de- 
fined as follows: 


0001H = read only file 
0002H = hidden file 
0004H = system file 
0010H = subdirectory 
0020H = file archive 


with other dev_attr combinations corresponding to reserved values. Dev_flag speci- 
fies the action to be taken if the file exists, where 


00000001B 
indicates that the file should be opened. The dev_mode parameter has the form 


Le 0 


bits DWFRRRRERERRIS S SRAAA 


where 


D 
W = OQ writes may be run through the DOS buffer cache 


QO means open in normal way 


TY 
Il 


Q errors reported through system error handler 
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R = QO reserved and must = 0 
I = 1 file handle is private to the current process 
SSS = 100° deny neither Read nor Write access 


AAA = 001 Write only access 
Hence 
dev_mode dw 0000000011000001B 


corresponds to file handle private, deny none, and write only. The parameter dev_rsv 
must be zero. We will return to the remaining data segment variables as the code 
segment API calls that use these variables are considered. 

Following the termination of the data segment, DATA, the code segment is 
developed. This segment, CSEG, opens with an ASSUME pseudo-op that associates 
each segment register with an appropriate segment name. Here both DS and ES are 
associated with DATA. Next a FAR procedure PRTSC1 is set up. Notice that the 
normal DOS program segment prefix (PSP) area is not required. The return is FAR 
and will be accomplished using 


@DosExit 1,0 


which automatically returns execution to the proper OS/2 entry point at the close of 
PRTSC1. In this API call the first parameter is set to 1 and causes all threads in the 
process to end. The second parameter is the result code, and this is used by any 
threads requiring input from the process prior to its termination. 

Upon entry to PRTSC1, DS is pushed on the stack and popped into ES. Then 
@DosOpen is called as discussed above. The return value from this call is in ax 
and, if 0, means that a normal open occurred. If ax is not zero, @DosExit is called. 
To understand the remaining instructions and macro calls, it is necessary to under- 
stand how the printer works in graphics mode. The @DosOpen macro opens LPT1 
(the line printer) as a file. This file can be written using the @DosWrite macro. The 
line printer used in this example is an EPSON FX-85 [5]. The @DosWrite macro 
can be used to pass characters for output to the printer as well as passing control 
codes. We would like to use the printer in graphics mode. 

The print head consists of a vertical array of eight pins. In graphics mode 
these pins have an associated weight as follows: 


PIN WEIGHT 


0 128 
° 64 
0 32 
O 16 


: 8 
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) 4 
° 2 
fe) 1 


Here three pins have been darkened to indicate that they are active. The total sum 
of the pin values for these darkened pins is 74; hence when in graphics mode, a 74 
output to the printer will cause these pins to print. Similarly, 255 would cause all 
pins to print. Also, 128 would cause only the top pin to print. 

How is the printer placed in graphics mode? Most of the printer control char- 
acters are of the form ESC... . To put the printer in single-density graphics mode the 
sequence 


ESC “K* (nl) (n2} 
must be sent. Using ESC = 1BH and “K” = 4BH, it follows that if 


nl = d MOD 256 
n2 INT (d/256) 


where d = total number of columns to be printed, then 
1BH, 4BH, 64D, OD1H 


corresponds to setting the printer in the graphics mode with a total of 320 printer 
columns active, out of a possible 480 for the FX-85. 

Returning to the code appearing in Figure 2.1, we see that the buffer, 
in_buffer(), is loaded with 320 values of 74 (the character value corresponding to 
the pins discussed earlier). Following the loading of this buffer the macro call 


@DosWrite dev_hand,in buffer3,bytesin3,bytesout 
is made. Here 
in_buffer3 = 1BH,41H,08H 


where the first character is ESC. The second character sets the vertical spacing to 
8/72-Inch line spacing: 


ESC A (8) 


The third parameter in all the @DosWrite calls is the buffer length, and the 
fourth parameter is the number of bytes written. The macro call 


@DosWrite dev_hand,in_buffer4,bytesin2,bytesout 
executes 


ESC 2 
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which implements the line spacing set above. The macro call 
@DosWrite dev_hand,in bufferl,bytesinl,bytesout 
sets up the call 
ESC K 64 1 


to specify 320 columns. This command must be followed by 320 characters. The 
command 


@DosWrite dev_hand,in buffer,bytesin,bytesout 


outputs 320 columns, corresponding to the 74 graphics combination already illus- 
trated. 
Next 


@DosWrite dev_hand,in_ buffer2,bytesin2,bytesout 


causes ODH and OAH to be output for the carriage return and line feed. This is fol- 
lowed by a reset of the graphics mode and a second print of the 320 values of the 
graphics mode 74. Figure 2.2a illustrates the output for this program. When the 
buffer value is changed from 74 to 255, all pins print. This case is illustrated in 
Figure 2.2b. 


(b) 


Figure 2.2 Printer output from prt2.asm (a) with fill character “74” and (b) 
with fill character “255”. 


The program appearing in Figure 2.1 illustrates the main features of how to ac- 
cess the API from assembler. Here the printer was accessed using API calls and 
placed in graphics mode as well as used to output graphics characters. In the next 
section we look at more complex programs that access the screen buffer. Since we 
have information about the screen pixels, it will be possible to develop a screen 
print program that uses the printer in graphics mode to print the screen. 
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2.3 ACCESSING THE VIDEO SERVICES 


To be able to access the screen context requires a knowledge of the physical 
memory associated with the display. This memory has different partitioning depend- 
ing on what display mode is being used. Typically, the graphics modes normally ac- 
cessed by the IBM PS/2 computers (and the IBM AT) are Color Graphics Adapter 
(CGA) mode, which is a 320-column by 200-row pixel screen, the Enhanced Graph- 
ics Adapter (EGA) mode, which is a 640-column by 350-row pixel screen, and the 
Video Graphics Adapter (VGA) mode, which is a 640-column by 480-row pixel 
screen. 


2.3.1 The Display Buffer 


In this chapter we access the CGA screen context. This is mode Hex 5. The 
memory is allocated into two buffer regions specified as follows: 


1. Even Scans (rows 0, 2, 4, ..., 198) starts at address B8O00H. 
2. Odd Scans (rows 1, 3, 5, ..., 199) starts at address BAOOOH. 
3. Each raster row occupies 80 bytes, where a byte has the following form: 


Pixels: N N+1 N+2 N+3 


Cl C0 Ci Co ei CO Ci C0 


with color section determined by 


Ci Co 

0 0 black 

0 1 light cyan 

1 0 light magenta 

1 1 intensified white 


4. Address B8000H contains the pixel information for the first four pixels in the 
upper left-hand corner. 


There is a second CGA mode, which is 640 columns by 200 rows; however, we 
will not consider this mode. We use the terms pel and pixel interchangeably herein. 

How does the actual location of a pixel! attribute get set based on row and 
column data about the screen? To locate the correct (row, col) byte in screen buffer 
physical memory, it must be remembered that the even-row value starts at location 


80 * (row/2) 


offset from B8000H. Similarly, recognizing that integer division truncates (3/2 
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becomes 1, ...), the same expression serves to locate an odd-row relative to 
BAOOOH. Since there are 80 bytes for 320 columns, we need to locate 


col/4 
Hence the offset location of a given byte in terms of (row,col) is given by 
80 * (row/2) + (col/4) 
This would correspond to the code 
mov ax,row 
shr ax,l 
mov dx,0 ; clear upper 
mul eighty 
mov bx,col 
shr bx,1l 


shr bx,l 
add ax,bx 


To identify an individual pixel within a byte, we note that the least significant 
bit (LSB) and LSB+1 correspond to the attribute positions for the fourth pixel, 
(LSB+2, LSB+3) correspond to the attribute positions for the third pixel, and so on. 
Hence 


We will simply turn the pixel on using a mask: 
MASK1 = 01H 


This will produce a light cyan screen color. Dividing col by 4 generates a remain- 
der (0,1,2,3), which is in reverse order to the pixel number (assuming that we start 
numbering the pixels within a byte 0,1,2,3). Hence 


3-col mod 4 
indicates the actual pixel position within the (row,col) byte. Starting with 
000000 0 1 


it is clear that a shift 


2 * (3-col mod 4) 
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will place 1 in bits 6, 4, 2, or 0 as needed to specify the pixel attribute. The follow- 
ing code uses the coprocessor to load xxx with this pixel value based on row, col: 


fild four 
fild col 


fprem 


smodulo 


fistp xx 
fistp dummy 


mov 
mov 
sub 
mov 
mul 
mov 


al,3 

bl,byte ptr xx 
al,bl 

ah,0 

two 

Gi, al 

al,MASK1 

al,cl 

XXx,C1 


*MASK1 


This, then, is a prescription for using a screen direct memory access (DMA) tech- 
nique to the video physical buffer, once that buffer has been accessed. 

The last code necessary to complete specification of a video buffer location is 
to specify the precise offset location for address above. Here we assume that the 
even-row or odd-row location must also be taken into consideration. Consider the 


code 


mov ax,row 

and ax,MASK11 

cmp ax,0 

jle ELSE1 
mov ax,address 
add ax,OFFSET1 
jmp IF11 


ELSE1: 


mov ax,address 


IF11:3 


mov bp,ax 
mov al,xxx 
or es:[{bp],al 


;MASK11=0001H 


;OFFSET1 = 2000H 


This code checks to see if the row is even or odd. If odd, an offset of 2000H 
is added to address. The full pixel byte offset is in address and the byte value in 
xxx. Assuming that the extra segment register contains the video segment selector 
value, then 
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ov es:[bp],al 
changes the bit values from 00 to 01 as needed for the pixel in question. 
2.3.2 Locking the Screen Context 


Figure 2.3a presents a function flowchart for a program that plots two lines across 
the screen. Figure 2.3b illustrates this program, which calls the video buffer and 
plots two parallel lines across the screen. The program also calls a routine scr_ld 
that loads an intermediate buffer, scr_buffer, with the screen context pixel values. 
This buffer is then used to output the display context to the printer. We will not 
focus on the routines that write the display context to the printer until Section 2.3.3. 
In this section we examine the video API calls. 

Consider the first executable instruction in the program the call to cls to clear 
the screen. The procedure cls, in turn, has a single call (besides the return): 


@VioScrollUp tr,lc,br,rc,no line,blank,viohdl 


The parameters appearing in this API call are among the first nine parameters 
appearing in the data segment. Viohdl] is a handle to the display. The parameters tr 
and Ic are the top row and left column to be scrolled. The parameters br and vc are 
the bottom row and right column to be subtended for the scroll operation. A pa- 
rameter no_line is the number of lines to be scrolled and blank the attribute to be 
used to replace each character (in this case a blank) pair. This routine effectively 
blanks the screen. 

Next the main FAR procedure sets the screen in CGA graphics mode. To do 
this the video API call is made referencing the video handle and a CGA structure 
that contains parameter data: 


@VioSetMode CGAm,viohdl 


The video CGA structure is specified in the data segment by the required parame- 
ter values between the statements 


CGAm label FAR 
vrCGA dw 200 


where the last value is the number of rows (the vertical resolution) on the CGA 
screen. Below this structure in the data segment is a second structure, STDm, which 
is used later with the call to return to text 80 x 25 mode. This structure spans the 
lines between 


STDm label FAR 


vr80 dw 400 
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SETUP BUFFER & 
DATA AREAS 


CLEAR SCREEN 


SET CGA MODE 


RE-CLEAR SCREEN 


LOCK DISPLAY 
CONTEXT 


GET PHYSICAL 
BUFFER 


DRAW LINES 


SETUP TEMPORARY 
PLOT BUFFER 


UNLOCK SCREEN 


HESITATE DISPLAY 


RETURN TO 
STANDARD MODE 


PRINT DISPLAY 
CONTEXT 


EXIT 
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Figure 2.3a Functional flowchart for 
boxprtl.asm, the program that calls the 
video buffer and plots two lines. 
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TITLE BOXPRT1 - This program checks print graphics (BOXPRT1.ASM) 


=e se Se Se Me 


DESCRIPTION: This program plots two lines in protected 
mode and hesitates using a keyboard delay. Graphics 
mode 05H is used to display the lines. 


-8087 
PUBLIC xx,xxx ;CodeView symbol map 
EXTRN prtscr:FAR,scr_1d:FAR 
IF1 

include sysmac.inc 
ENDIF 

-sall ;Suppresses macro lists 
dgroup GROUP data 
STACK SEGMENT PARA STACK 'STACK'! 

db 256 dup('STACK ') 
STACK ENDS 
DATA SEGMENT PARA PUBLIC 'DATA' 
PUBLIC in_buffer,bytesin,bytesout,in_bufferl,bytesinl 
PUBLIC in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
PUBLIC dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
PUBLIC dev_mode,dev_rsv,MM,coli1,N 
PUBLIC s,eight,eighty,four,shift1,scr_buffer 
PUBLIC sixforty,N4,ddd,w,bl 
viohdl equ 0) ;Required video handle 
result dw ) ;Completion code 
action equ 0) ;Terminates current thread 
tr dw 0 ;Top row screen clear 
le dw 0 ;Left column screen clear 
br dw 23 ;Bottom row screen clear 
re dw 79 ;Right column screen clear 
no_line dw 25 ;Number lines scrolled 
blank dw 0007H ;Blank character pair 
CGAm label FAR ;Video mode structure-CGA 
lmodeE dw 12 ;Structure length 
typeCGA db 00000111B ;Mode identifier 
colCGA db 2 ;Color option-Mode 5 
txtcCGA dw 40 ;text characters/line-ignore 
txtrCGA dw 25 ;text lines-ignore 
hrCGA dw 320 ;horizontal resolution 
vrCGA dw 200 ;vertical resolution 
STDm label FAR ;Video mode structure-80x25 
lmode8s0 dw A Be ;Structure length 
types8s0 db 00000001B ;Mode identifier-Mode 3+ 
col8s0 db 4 ;Color option 
txtc80 dw 80 ;text characters/line 
txtr80 dw 25 ;text lines 
hr8s0 dw 720 ;horizontal resolution 
vr8s0 dw 400 ;vertical resolution 
kbd_buf db 80 ;Keyboard buffer 
lkbd buf dw $-kbd_buf ;Length keyboard buffer 
iowait dw 0 ;Wait for CR 
kbdhdl equ fe) ;Keyboard handle 
waitf equ 1 ;Screen waiting status 
dstat db Fd ;Returned status 


Figure 2.3b Program code for boxprtl.asm. 
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PVBPtr1 label FAR ;Video buffer structure 
bufstl dd OB8000H ;Start physical address 
buflenl dd 4000H ;Buffer length 

physell dw ;0S/2 screen buffer selector 


MASK1 db ;PEL byte mask 

MASK11 dw ;Odd/even row mask 
OFFSET1 dw ;Odd row buffer offset 
four dw 

xX dw 3 ;PEL modulo parameter 
dummy dw : 780287 dummy "pop" 
two db 

XXX db 3 ;Output value 

eighty dw 

row dw E 7;QCOW 

col dw : ;column 

address dw : ;Address screen dot 


dw : ;Box col parameter 
dw 3 ;Box row parameter 
dw ;Start column 

dw ;End column 

dw ;Start row 


in_buffer 320 dup(0) ;print buffer 

bytesin dw ;CGA line 

bytesout 0) ;output count 
in_bufferl 1BH,4BH,64D,01H ;printer setup 

bytesinl 4 ;count bytes In_bufferl 
in_buffer2 ODH, OAH ;LF/CR 

bytesin2 2 ;in_buffer2 byte count 
in_buffer3 1BH,41H,08H 

bytesin3 3 ;in_buffer3 byte count 
in_buffer4 1BH, 32H 


dev_name "LPT1* , 0 ;name of printer device 
dev_hand 0 ;device handle 

dev_act ) ; 
dev_size 0) : 
dev_attr (e) ; 
dev_flag 00000001b ;Open File 

dev_mode 0000000011000001b ;hdl private,deny none,w/o 
dev_rsv 0 ;reserved 

N4 ? 

MM 40H,10H,04H,01H ;pel mask 

w 128,64 ,32,16,68;,4;2 41 ;pin weights 

coll 320 dup(?) ;column index-printer 

bl 4 dup(?) 

N ? 

shiftl 6,4,2,0 
s 4 dup(?) ;dup copies pel byte 

ddd ? 

sixforty 640 

scr_buffer 16384 dup(0) ;temporary buffer--screen values 


;printer line 


e 
’ 
. 
’ 


Figure 2.3b (Continued) 
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ENDS 


se O se se Ne 


Q 

n > 
53] 4 
Q > 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dgroup 
PROC FAR 


call cls ;Clear screen 
@VioSetMode CGAm,viohdl ;Set CGA Graphics mode 
call clsCGA ;Clear CGA screen 


@VioScrLock waitf,dstat,viohdl ;Lock screen context 


@VioGetPhysBuf PVBPtr1,viohdl ;Get physical buffer selector 
push physell ;Save selector 
pop es ;Load selector into extra segment 


mov ax,0O 
mov y,ax 

call lineh ;Draw line 

mov ax,100 

mov y,ax 

call lineh ;draw second line 


° 
U 


call scr_ld 


@VioScrUnLock viohdl Unlock screen context 


@KbdStringIn kbd_buf,1lkbd_buf, iowait,kbdhdl ;hesitate 


@VioSetMode STDm,viohdl 780 x 25 alpha mode 


call prtscr 


@DosExit action,result ;Terminate process 


ENDP 


PROC 


NEAR 


@VioScrollUp tr,1lc,br,rc,no_line,blank,viohdl 
ret 


cls ENDP 


U 


clsCGA PROC NEAR 


@VioScrLock waitf,dstat,viohdl ;Lock screen context 
@VioGetPhysBuf PVBPtr1,viohdl ;Get physical buffer 
push physell ;Screen selector 

pop es ;Load extra segment 


mov bp,O ;Start offset zero 
mov al,O ;Zero attribute-clear 
DO1: 


mov es:[bp],al ;Clear byte 

inc bp 

cmp bp,1F3FH ;Check end 1st buffer 
jle DO1 


mov bp,2000H ;Offset 2nd buffer-odd 
mov al,O ;Zero attribute-clear 


mov es:[bp],al ;Clear byte 
inc bp 
cmp bp,3F3FH ;Check end 2nd buffer 


Figure 2.3b (Continued) 
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jle DOo2 
@VioScrUnLock viohdl 


ret 
ENDP 


PROC NEAR 
(col,row) = (x,y) 


fild four 
fild col 
fprem 

fistp xx 
fistp dummy 
mov al,3 

mov bl,byte ptr xx 
sub al,bl 
mov ah,O 

mul two 

mov cl,al 
mov al,MASK1 
shl al,cl 
mov xXxXxX,al 


mov ax,row 
shr ax,1l 
mov dax,0 
mul eighty 
mov bx,col 
shr bx,1 
shr bx,1 
add ax,bx 
address,ax 
ax, row 
and ax,MASKil 
ax,0 
jle ELSE1 
mov ax,address 
add ax,OFFSET1 
jmp IF11 


mov ax,address 


mov bp,ax 
mov al,xXxXx 


or es: [bp],al 


ret 
ENDP 


PROC NEAR 


row position, xb 


ax,y 
row,ax 


ax,0 

xb,ax 
ax,319 
xe,ax 
ax, xb 


begin, xe 
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;Unlock screen context 


;Load stack with 4 

7ST = col, ST(1) = 4 
;Modulo 

;Store remainder in xx 
;Pop stack 


7(3 = col % 4) 
;Clear upper multiplicand 


;Shift value for PEL 
7;PEL color mask 
;Shift to correct PEL 
;Store buffer value 


e 
’ 


;Begin address calculation 
;Divide row by 2 

;Clear upper multiplicand 
;Convert column value to bytes 
;offset in ax 

;Save offset base 


;Check even/odd row 
;Look for bit 0 set 


;add odd buffer offset 


7;screen buffer address 
sAttribute value for dot 


;Write dot 


= end 
;Establish row for wdot 


e 
Ud 


;x-begin position for line 
;x-end position for line 


;Establish start column 


Figure 2.3b (Continued) 
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mov col,ax 

push ax ;Save column value 

call wdot ;Write dot (col,row) 

pop ax ;Recall column 

inc ax ;Increment column 

cmp ax,xe ;Check end horizontal line 


jle DO10 


ret 
ENDP 


ENDS 
END OS21 


Figure 2.3b (Concluded) 


appearing in the data segment. Finally, a call to clsCGA is made, which reclears the 
screen in CGA mode. This call is needed because the switch to CGA mode leaves 
the screen in an unpredictable state. The call to clsCGA is somewhat different than 
the prior cls call because the screen is now in CGA mode and the screen context 
must be locked prior to accessing it. 

In the procedure clsCGA, the first executable statement is the macro call 


@VioScrLock waitf,dstat,viohdl 


This call locks (or requests ownership) of the physical display buffer. The flag waitf 
is OQ if the screen is not available; otherwise, it is 1. The status, dstat, is 0 if the lock 
is successful; otherwise, it is 1, and viohdl is the video handle. Once this routine is 
executed the physical buffer may be accessed. This is accomplished using the state- 
ment 


@VioGetPhysBuf PVBPtrl,viohdl 


Here PVBPtrl is a structure with the form (see data segment) 


PVBPtrl label FAR 


bufstl dd OB8000H 
buflenl dd 4000H 
physell dw 0 


The first parameter in this structure, bufstl, is the start address of the physical dis- 
play buffer specified as a 32-bit physical address. We see that this is merely the 
beginning of the CGA even-row buffer space, as described above for normal IBM 
memory allocation (B8000H). The second parameter, buflen1, is the length of the 
buffer, which is 4000H or 16384 bytes long. Finally, physell is the physical selec- 
tor which is returned by the call. Upon completion of the call the physical selector 
value is immediately loaded in the extra segment register es. Hence, es then points 
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to the beginning of the physical buffer. This step is very important because it 
confirms the translation of the segment registers and the segment arithmetic for 
calculating a physical or virtual address. Following the loading of the selector 
address, the two buffer regions are cleared: even rows (offset 0-1F3FH) and odd 
rows (offset 2000H-3F3FH). Then the screen context is unlocked with the call 


@VioScrUnlock viohdl 


The actual screen write is accomplished using two calls to the procedure lineh, one 
call at y value O and one call at y value 100 (halfway down the screen). The form 
of lineh use in this program merely draws a straight horizontal line from column 0 
to column 319 of the screen. The actual drawing of the dot is accomplished by a 
procedure wdot, which implements the techniques of section 2.3.1 discussed earlier. 

Following the plotting of the two horizontal lines on the display, the screen 
context is loaded in the buffer, scr_buffer, based on a call to scr_ld. Eventually, the 
screen is printed using prtscr, which employs this buffer as a template of the screen 
context. The screen is next unlocked and the keyboard pause or hesitation is insti- 
tuted with the call 


[@kbdStringIn kbd _buf,1lkbd_buf,iowait,kbdhdl 


Here kbd_buf is a buffer for a character string that is 80 bytes wide. The variable 
1kbd_buf is the length of this buffer. A value of 0 for iowait indicates that the 
system should wait or hesitate if a character is not available. The parameter kbdhdl 
is the handle to the keyboard device context. This call, of course, pauses the action 
and allows the user to view the screen. 

The second call to @VioSetMode returns the video context to 80 x 25 text 
mode. Calling prtscr prints the intermediate screen buffer on the printer as described 
above. Finally, @DosExit causes the program to exit back to OS/2. Figure 2.4 is the 
actual print of the screen output. 
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Figure 2.4 Output print screen from boxprtl.asm (Figure 2.3b). 
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2.3.3 Printing the Graphics Screen under OS/2 


In Figure 2.3 a portion of the data segment was devoted to parameters and variables 
used by scr_Id and prtscr for the printer dump of the screen context. These variables 
appeared earlier in the program of Figure 2.1, where a simple graphics print output 
was generated. In this section we address the topic of how to achieve a printout of 
the graphics screen context. This is similar to employing GRAPHICS.COM under 
DOS except that our screen print program does noi run in the background but is 
directly callable by the program executing. IBM and Microsoft did not provide the 
equivalent of GRAPHICS.COM with their system software during the early releases 
of OS/2. Hence this program is both useful for obtaining a hard copy of the graph- 
ics screen and as information for illustrating the combined techniques of display 
access and graphics printer output. 

We have seen how to access the screen physical buffer using API calls. Also, 
we saw a routine, scr_ld, used ostensibly to load a buffer scr_buffer. Figure 2.5 
illustrates this routine and we see it is a very simple procedure with no API calls. 
Only the byte array, scr_buffer, is external. The routine also interleaves the even and 
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TITLE SCRLD -- This routine loads the screen print buffer (scrld.asm) 


DESCRIPTION: This routine accompanies prtscr to load 
and print the screen in 320 x 200 mode. 

The prtscr buffers are assumed loaded. This is an OS/2 
routine. 


/ 
t 
’ 
, 
EXTRN scr_buffer: BYTE 


-Sall 

CSEG SEGMENT PARA PUBLIC 'CODE' 
PUBLIC ser ld 

scr_ld PROC FAR 


ASSUME CS:CSEG 


mov cx,100 ;no. of raster pairs 


mov di,O ;index to screen buffer 

mov si,0O ;index to dummy array 
DO55: 

push cx 


DO56: 


scr 1d 
CSEG 


mov cx,80 


mov al,es: [di] 

mov ah,es:[di+2000H] 
lea bx,scr_buffer[0] 
mov ds:[bx+si],al 
mov ds: [bx+si+80],ah 
inc si 

inc di 

loop DO56 


add si,80 
pop cx 
loop DO55 


ret 
ENDP 
ENDS 
END 


;raster row length 


;load even row physical buffer 
;0dd row physical buffer 
;dummy buffer 

;load even rows 

;0odd rows 


;skip to next double set 


Figure 2.5 Routine to set up temporary screen print buffer. 


Sec. 2.3 Accessing the Video Services 63 


odd rows from the physical buffer regions into a single buffer area which represents 
the full screen context in contiguous fashion. 

Figure 2.6a illustrates the function flowchart for the print screen routine. Figure 
2.6b contains the actual print screen routine. All the printer parameters referenced in 
the earlier data segments appear as external variables and are defined as such at the 
beginning of the program. Following the usual loading of sysmac.inc, the program 
starts immediately with the code segment, CSEG. The routine prtscr is declared 
PUBLIC. In general, our approach will be to treat prtscr and scr_Id as externally 
callable modules whenever a printer screen dump is desired. Hence these two 
modules will become workhorse functions for illustrating graphics displays and the 
reader can expect to encounter them throughout the book. Shortly we will install 
them in a general-purpose library GRAPHLIB.LIB where they will be universally 
accessible. The only difficult part about programming in this fashion is the large 
data segment areas that are needed to set up the calls to these printer procedures 
(and the screen parameter areas). 

Returning to Figure 2.6, we see immediately the usual call, @DosOpen, to 
open the printer device context. This was discussed in reference to Figure 2.1. Since 
this program returns to a calling procedure, the ret instruction is implemented rather 
than @DosExit. The sequence of API calls to @DosWrite is generally in agreement 
with the earlier programming of Figure 2.1 except that the double output is omitted. 
A loop is set up to increment 25 times, once for each eight-line graphics print. This 
yields a total of 200 rows displaced vertically. These rows correspond to the actual 
screen buffer rows for the raster scan. Since each row of the screen buffer consists 
of 80 bytes of pixel data, eight rows at a time correspond to blocks of 640 bytes of 
data. 

The call to Idarray sets up the output for the printer eight rows at a time. 
Basically, a small 32-element buffer, col1[], is loaded with the four pixels’ worth of 
data contained in each byte of the physical display buffer. This is done for the same 
byte from eight consecutive rows of the screen buffer. Hence Idarray sets up a group 
of pixel data representing a block of the screen context. To do this an array of four 
elements, s[O] to s[3], is loaded with a byte of the screen buffer data from 
scr_buffer. Each pixel is then masked off from its position in this byte, shifted, and 
weighted to generate the correct graphics printer character. The weights, for ex- 
ample, contained in the array, w[], must be specified in the calling program’s re- 
served printer data area in the usual fashion. It is this technique that is used to load 
the array coll1[]. 

Returning to prtscr itself, we see that after each eight-line block by 320 col- 
umns is loaded and in_buffer[] properly loaded the graphics print is implemented. 
This is in the fashion of Figure 2.1 and is followed by a carriage return and line 
feed. Once the complete screen dump to the printer has been accomplished, prtscr 
closes the printer device handle with 


@DosClose dev_hand 


and returns to the calling routine. 
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OPEN PRINTER 
DEVICE 
i 
N 
INCREMENT CLOSE PRINTER 
LINE COUNT DEVICE 
LOAD EXIT 
PRINTER ARRAY 


INCREMENT 
ROW POINTER 
LOAD 
PRINTER BUFFER 


WRITE 
PRINTER BUFFER 
LF & CR 


INCREMENT BUFFER 
POSITION 640 


Figure 2.6a Functional flowchart for 
prtscr, the screen dump routine. 
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Figure 2.6b 
captured. 
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prtscr - print screen (prtscr.asm) 


DESCRIPTION: This routine prints the screen in 
320 x 200 CGA mode. This routine needs the 
following data items in the calling routine 
data segment: 


MM: BYTE, 


in_buffer 320 dup(0) 
bytesin 320 

bytesout 0 

in_buffer1l 1BH,4BH, 64D, 01H 
bytesinl 4 

in_buffer2 ODH, OAH 
bytesin2 2 

in_buffer3 1BH, 41H, 08H 
bytesin3 3 

in_buffer4 1BH, 32H 


dev_name *LPT1* ;0 

dev_hand 0) 

dev_act 0) 

dev_size 0 

dev_attr 0 

dev_flag 00000001b 
dev_mode 0000000011000001b 
dev_rsv dd 


, 
MM 40H, 10H, 04H, 01H 
W 128,64 ,32,16,8,4;2,1 
coll 320 dup(?) 

? 


N 
N4 ? 

s 4 dup(?) 
shiftl 6,4,2,0 
eight 8 

eighty 80 

bl 4 dup(?) 
four 4 

ddd ? 
sci_buffer 16192 dup(0) 
sixforty 


w: BYTE,coll1: BYTE 


in_buffer: BYTE, in_buffer1: BYTE, in_buffer2: BYTE 
in_buffer3:BYTE,in_buffer4: BYTE 


bytesin: 


WORD, bytesin1l: WORD, bytesin2:WORD, bytesin3:WORD 


bytesout:WORD,dev_name: BYTE, dev_hand: WORD 


dev_act: 


WORD, dev_size:DWORD,dev_attr:WORD 


dev_flag:WORD,dev_mode:WORD,dev_rsv: DWORD 
N:WORD,N4: WORD 

eighty:WORD,eight:WORD, four:WORD,s:BYTE,shiftl1:BYTE 
scr_buffer: BYTE,ddd:WORD,b1:BYTE,sixforty:WORD 


include 
-sall 


SEGMENT 
PUBLIC 


Routine 


sysmac.inc 


PARA PUBLIC 'CODE' 
prtscr 


to print the screen once the physical display buffer is 
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prtscr PROC 


Introductory OS/2 Assembler Programming 


FAR 


ASSUME CS:CSEG 


;open device 


Chap. 


@DosOpen dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag,dev_mode,dev_rsv 


ELSE1: 


LOOP1: 


LOOP2: 


DII1: 


prtscr 


ldarray 


se se Se Se Ne 


DO110: 


cmp 


ax,0 


je ELSE1 


ret 


;Exit 


sinitialize device 


@DosWrite dev_hand,in_buffer3,bytesin3,bytesout 
@DosWrite dev_hand,in_buffer4,bytesin2,bytesout 


mov 
mov 


ax,25 
si,0O 


push dx 
push si 


mov 
mul 
mov 


ax,si 
sixforty 
N,ax 


call ldarray 


mov 
mMOv 


Mov 
Mov 
mov 
mov 
mov 
mov 
mov 
mov 
add 


di,oO 
cx, 80 


al,coll[di] 
in_buffer[diJ,al 
al,coll[@i+1] 
in_buffer[dit+1],al 
al,coll[di+t2] 
in_buffer[di+2],al 
al,col1[di+3] 
in_buffer[di+3],al 
di,four 


loop LOOP2 


’ 


;number print lines(+1) 
;index to 8 row block 


;preserve dx 


;preserve block count 


3640 block size 
;Save in N 


’ 


e 
’ 


sinitialize 320 column counter 
;count of column bytes 


;column 1 from byte 
;load print buffer 
;column 2 from byte 
;load print buffer 
;column 3 from byte 
;load print buffer 
;column 4 from byte 
;load print buffer 


;increment column index 


;write print row 


@DosWrite dev_hand,in_bufferl,bytesinl,bytesout 
@DosWrite dev_hand,in_buffer,bytesin, bytesout 
@DosWrite dev_hand,in_buffer2,bytesin2,bytesout 


pop 
pop 
dec 
inc 
cmp 
jle 


si 
ax 
ax 
si 
ax,0 
DII1 


jmp LOOP1 


@DosClose dev_hand 


ret 


endp 


PROC 


NEAR 


’ 


recall block count 


;recall print line count 


;decrement count 


;increase block count 
;check 25 lines printed 


;close print device 


N is the printer row # - 640 byte intervals [0,24] 
MM[O] = 40H,...,MM[3] 


w[0] 


mov 
mov 


mov 
mov 
inc 


si,O 
cx,320 


al,0 
coll[{si],al 
si 


01H (pel mask) 


= 128,w[1l] = 64,...,w[7] =1 


column count initialization 


7320 columns 


;clear print buffer 


s;increment column count 


Figure 2.6b (Continued) 


Sec. 2.3 


Accessing the Video Services 


loop DO110 


mov 
mov 
mov 


Mov 
mov 
mov 


si,0O 
N4,sSi 
ax, 80 


di,0 
ddd,di 
cx, 8 


push cx 


Mov 
add 


bp, ddd 
bp,N 


push bx 


lea 
add 
mov 
pop 
mov 
mov 
mov 
mov 


and 
mov 
shr 
mov 
mul 
mov 


mov 
and 
mov 
shr 
mov 
mul 
mov 


mov 
and 
mov 
shr 
mov 
mul 
mov 


mov 
and 
mov 
shr 
mMOv 
mul 
mov 


bx,scr_buffer[0] 
bp, bx 

al,ds: [bp+si] 

bx 

s[0],al 

s{1],al 

s[2],al 

s(3],al 


al,MM[0] 
cl,shift1[0] 
al,cl 

ah,0 

w([di] 
b1[0],al 


al,s[1] 
al,MM[1] 

el, shifti[1] 
al,cl 

ah,O 

w[di] 
b1[1],al 


al,s[2] 
al,MM[2] 
cl,shift1[2] 
al,cl 

ah,0O 

w[di] 
b1[(2],al 


al,s[3] 
al,MM[3] 
cl,shift1[3] 
al,cl 

ah,0 

w[di] 
b1[3],al 


push bx 


Mov 
Mov 
add 
mov 
add 
mov 
add 
mov 
add 


pop 


bx,N4 
al,b1[0] 
colli[bx],al 
al, bL[1Lj 

coli (bxt+1],al 
al,b1[2] 
coli[bx+2],al 
al,b1[3] 
coll[bx+3],al 
bx 
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e 
’ 


;index into 80 bytes/row 
7;N4 = row byte block count 
;counter - row bytes 


;raster row counter (1 of 8) 
780 block counter 
;raster row counter 


;preserve row count 

sbp = # 80 byte blocks 

;add printer line count 
;preserve bx 

;load address screen buffer 
;add to index 

74 pel bytes 


;1lst copy 

72nd copy 

73rd copy 

74th copy 

71st pel mask 

;load 1st pel shift 
;shift right 

;clear upper 

;multiply by weight (row) 
;save lst printer column 


;load 2nd pel 

;mask 2nd pel 

load 2nd pel shift 
;shift right 

;clear upper 

;multiply by weight (row) 
;save 2nd printer column 


;load 3rd pel 

;mask 3rd pel 

;load 3rd pel shift 
;shift right 

;clear upper 

;multiply by weight (row) 
;Save 3rd printer column 


load 4th pel 

;mask 4th pel 

;load 4th pel shift 

;shift right 

;clear upper 

;multiply by weight (row) 
;save 4th printer column 
;preserve bx 

;counter into print buffer 
;load column N4 


z;load column N4+1 
;load column N4+2 


;load column N4+3 


Figure 2.6b (Continued) 
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pop cx ;recall print block row index 


ine di ;increase print block row counter 
add ddd,8s0 ;increase byte count 
dec cx ;decrease row bound 
cmp cx,0 
jle DO133 
jmp DO112 
DO133: 
add N4,4 ;add 4 columns to index 
dec dx ;decrement row bytes 
inc si ;increase screen buffer index 
cmp dx,0 
jle DII2 
jmp DO111 
DII2: 
ret 


ldarray ENDP 


CSEG ENDS 
END 


Figure 2.6b (Concluded) 


Figure 2.7a presents a Structure Chart for the modularized boxprtl.asm pro- 
gram. Figure 2.7b presents a modularized version of the earlier boxprtl.asm pro- 
gram. Here all the graphics and print routines have been assembled as separate 
modules. Only the large data segment areas are present with the small FAR proce- 
dure that actually plots and prints the two lines. 


000 


PLOT/PRINT 
TWO PARALLEL 
LINES 


200 300 
ACCESS PRINT 


SCREEN SCREEN 


210 220 230 240 


LOCK PLOT SAVE UNLOCK SCREEN, 
SCREEN & HORIZONTAL SCREEN HESITATE, AND 
SET MODE LINES BUFFER RETURN 


Figure 2.7a Structure Chart for modularized boxprtl.asm program. 


Figure 2.8 illustrates a module that is used to build GRAPHLIB.LIB, a graph- 
ics and print library. This module contains the routines needed by twoln.asm to 
develop the two-line output in modular fashion. There is only one difference: In the 
twoln.asm program the length of the lines must be specified in the routine lineh. 
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This was implemented to be 320 columns with the earlier version of lineh. That 
version was used with twolin.asm, and we have illustrated the more general lineh in 
Figure 2.8 because it is characteristic of what appears in GRAPHLIB.LIB. Here, the 
beginning and ending column values must be specified in xb and xe, respectively. 


PAGE 55,132 
TITLE TWOLN - This program plots/prints 2 lines (twoln.asm) 


DESCRIPTION: This program plots two lines in protected 
mode and hesitates using a keyboard delay. Graphics 
mode 05H is used to display the lines. 
prtscr:FAR,scr_1d:FAR,cls:FAR,C1SCGA: FAR, 1lineh:FAR 
include sysmac.inc 
-sall ;Suppresses macro lists 
dgroup GROUP data 
STACK SEGMENT PARA STACK 'STACK'! 


db 256 dup('STACK ‘') 
STACK ENDS 


DATA SEGMENT PARA PUBLIC 'DATA' 


PUBLIC in_buffer,bytesin,bytesout,in_bufferl,bytesin1l 
PUBLIC in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
PUBLIC dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
PUBLIC dev_mode,dev_rsv,MM,col1,N 

PUBLIC s,eight,eighty,four,shiftl 

PUBLIC sixforty,N4,ddd,w,b1,scr_buffer 


PUBLIC xx,xxx,tr,lc,br,rc,no_line,blank,viohdl,PVBPtr1,physell,waitf 
PUBLIC dstat,four,two,col,dummy,MASK1,MASK11,row,eighty,address 
PUBLIC OFFSET1,y,xb,xe 


’ 

viohdl ;Required video handle 
result ;Completion code 

action ;Terminates current thread 
bs ;Top row screen clear 

Le ;Left column screen clear 
br ;Bottom row screen clear 
rc ;Right column screen clear 
no_line ;Number lines scrolled 
blank ;Blank character pair 


, 

CGAm ;Video mode structure-CGA 
lmodeE ;Structure length 

typeCGA 00000111B ;Mode identifier 

colCGA 2 ;Color option-Mode 5 

txtcCGA 40 ;text characters/line-ignore 
txtrCGA 25 ;text lines-ignore 


Figure 2.7b Modularized program twoln.asm. 
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hrCGA daw 
vrCGA dw 


sTDm label 


lmodes0 dw 
types0 db 
col8s0 ab 


txtc80 dw 
txtr8s0 dw 


hr8s0 daw 
vr8sg0 daw 
kbd_buf db 


lkbd_buf dw 


iowait dw 


kbdhdl equ 


’ 


waitf equ 


dstat db 
PVBPtr1 label 
bufst1 dd 
buflenl dd 
physell dw 
MASK1 dab 
MASK11 dw 
OFFSET1 dw 
four aw 
XX dw 
dummy dw 
two db 
XXX db 
eighty dw 
row dw 
col dw 


address dw 


x dw 
y dw 
xb dw 
xe dw 
yb dw 
ye dw 
eight dw 


=e se Se Se Se Ne 


in_buffer 
bytesin dw 
bytesout 
in_bufferl 
bytesinl 
in_buffer2 
bytesin2 
in_buffer3 
bytesin3 
in_buffer4 


e 
’ 


dev_name 
dev_hand 
dev_act 
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320 
200 


FAR 


12 


00000001B 


4 
80 
25 
720 
400 


80 


$-kbd_buf 


0 
0 


1 
5 


FAR 
OB8000H 
4000H 


320 dup(0) 


0 


1BH,4BH,64D,01H 


4 
ODH, OAH 
2 


1BH, 41H, 08H 


3 
1BH, 32H 


“LPr1* 0 
0) 
0) 


shorizontal resolution 
;vertical resolution 


;Video mode structure-80x25 
;Structure length 

;Mode identifier-Mode 3+ 
;Color option 

;text characters/line 

;text lines 

shorizontal resolution 
;vertical resolution 


;Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
;Returned status 


;Video buffer structure 
;Start physical address 
;Buffer length 

;0S/2 screen buffer selector 


*;PEL byte mask 
;Odd/even row mask 
;Odd row buffer offset 


;PEL modulo parameter 
780287 dummy "pop" 


;Output value 


7;COW 
7;column 
;Address screen dot 


7;Box col parameter 
;Box row parameter 
;Start column 

7;End column 

;Start row 

7;End row 


es a a ae ws we es ee ws ee ww we ew we we i 


;print buffer 

;CGA line 

;output count 

sprinter setup 

;count bytes In_bufferl 
;LF/CR 

;in_buffer2 byte count 


;in_buffer3 byte count 


;name of printer device 
;device handle 


e 
’ 


Figure 2.7b (Continued) 
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dev_size 0 ; 
dev_attr 0 ; 
dev_flag 00000001b ;Open File 
dev_mode 0000000011000001b shdl private,deny none,w/o 
dev_rsv fe) ;reserved 


N4 rs 
MM 40H,10H,04H,01H ;pel mask 

W 128,64,32,16,8,4,2,2 ;pin weights 
coll 320 dup(?) ;column index-printer 
bl 4 dup(?) 

N ? 

shiftl 6,4,2,0 

s 4 dup(?) 

ddd 2 

sixforty 640 
scr_buffer 16384 dup(0) 


;printer line 


;dup copies pel byte 


;temporary buffer--screen values 


=e One se Se Se Ne 


Q 

n Pp 
WB ww 
Q PY 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dgroup 
PROC FAR 


call cls ;Clear screen 


@VioSetMode CGAm,viohdl ;Set CGA Graphics mode 


call clsCGA ;Clear CGA screen 


@VioScrLock waitf,dstat,viohdl ;Lock screen context 


@VioGetPhysBuf PVBPtr1,viohdl 
push physell 
pop es 


;Get physical buffer selector 
;Save selector 
;Load selector into extra segment 


mov ax,0O 
mov y,ax 
call lineh 
mov ax,100 
mov y,ax 
call lineh 


;Draw line 


;draw second line 
call scr_ld ;loads the temporory buffer 


@VioScrUnLock viohdl ;Unlock screen context 


shesitate 


@KbdStringIn kbd_buf,1lkbd_buf,iowait,kbdhdl 


@VioSetMode STDm,viohdl 780 x 25 alpha mode 


call prtscr ;prints temporary buffer 


@DosExit action,result ;Terminate process 
ENDP 
ENDS 
END 


Figured 2.7b (Concluded) 
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TITLE GRAPH1 - This program is part of graphlib.lib(graph1.AsM) 


: DESCRIPTION: cls,clsCGA,wdor,and lineh routines 


include sysmac.inc 


tr:WORD,1c:WORD,br:WORD,rc:WORD,no_line:WORD, blank: WORD 
EXTRN viohdl:WORD, PVBPtri1: FAR, physel1:WORD,waitf:WORD 
EXTRN dstat: BYTE, four: WORD, col:WORD, xx:WORD, dummy : WORD 
EXTRN MASK1: BYTE, xxx: BYTE, row: WORD, eighty: WORD, address: WORD 
EXTRN MASK11:WORD, OFFSET1:WORD, y: WORD, xb: WORD, xe: WORD 
two:WORD 


SEGMENT PARA PUBLIC 
assume cs:cseg 
PUBLIC cls,clsCGA,wdot,lineh 


"CODE ' 


PROC FAR 


@VioScrollUp tr,lc,br,rc,no_line,blank,viohdl 
ret 


ENDP 


c1sCGA 


e 
, 


PROC FAR 
@VioScrLock waitf,dstat,viohdl ;Lock screen context 

@VioGetPhysBuf PVBPtr1,viohdl ;Get physical buffer 

push physell ;Screen selector 

pop es ;Load extra segment 


mov bp,O ;Start offset zero 
mov al,O ;Zero attribute-clear 


mov es:[bp],al 
inc bp 

cmp bp,1F3FH ;Check end 1st buffer 
jle DO1 


;Clear byte 


mov bp,2000H ;Offset 2nd buffer-odd 
mov al,O ;Zero attribute-clear 


mov es:[bp],al ;Clear byte 

inc bp 

cmp bp, 3F3FH ;Check end 2nd buffer 
jle Do2 

@vioScrUnLock viohdl ;Unlock screen context 
ret 


clsCGA 


waot 


ENDP 


PROC FAR 


; (col,row) = (x,y) 
fild four ;Load stack with 4 
fild col ;ST = col, ST(1) = 4 


Figure 2.8 Listing of partial content of GRAPHLIB.LIB. 
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fprem 

fistp xx 
fistp dummy 
mov al,3 

mov bl,byte ptr xx 
sub al,bl 
mov ah,O 

mul two 

mov cl,al 
mov al,MASK1 
shl al,cl 
mov xXxXx,al 


mov ax,row 

shr ax,l 

mov dx,0 

mul eighty 

mov bx,col 

shr bx,1 

shr bx,1 

add ax,bx 

mov address,ax 

mov ax,row 

and ax,MASK11 

cmp ax,0 

jle ELSE1 
mov ax,address 
add ax,OFFSET1 
jmp IF11 


mov ax,address 


mov bp,ax 
mov al,xXxx 


or es: [bp],al 


ret 
ENDP 


PROC FAR 


= row position, xb = begin, xe 


ax,y 
row,ax 


ax, xb 


col,ax 
push ax 
call wdot 
pop ax 
inc ax 
cmp 
jle 


ret 
ENDP 


ENDS 
END 
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;Modulo 
;Store remainder in xx 
;Pop stack 


3;(3 - col 4 4) 
;Clear upper multiplicand 


;Shift value for PEL 
7;PEL color mask 
Shift to correct PEL 
;Store buffer value 


e 
’ 


;Begin address calculation 
;Divide row by 2 

;Clear upper multiplicand 
;Convert column value to bytes 
;offset in ax 

;Save offset base 


;Check even/odd row 
;Look for bit 0 set 


;add odd buffer offset 


;screen buffer address 
;Attribute value for dot 


*Write dot 


= end 


;Establish row for wdot 


° 
, 
. 
' 


Establish start column 


;Save column value 

;Write dot (col,row) 
;Recall column 

;Increment column 

;Check end horizontal line 


Figure 2.8 (Concluded) 


74 Introductory OS/2 Assembler Programming Chap. 2 


2.3.4 Connecting Line Graphics with OS/2 


Consider two disjoint points on the screen at coordinates (x,,y,) and (x,,y,), respec- 
tively. (Assume that x, corresponds to a column value (1,320) and y corresponds to 
a row value [1,200].) If we are plotting a dot at these points, it is desirable perhaps 
to link two points with a line to show connectivity. Since there may exist pixels on 
the screen between these two points, a program could fill in these pixels and the 
screen would appear to have a line connecting the two points. To do this, we use 
the equation for a straight line: 


Y¥,=Y_. + M(x, —X,) 
Here the slope is 


Les 


m= 
oe ia 

We have used y, and x, as dummy variables to represent the intermediate points in 

question. 

Unfortunately, the density of dots available on the IBM Color Graphics 
Adapter screen is at most 320 x 200 or 640 x 200. Although this seems like a lot 
of points, the screen is large and frequently the connecting lines appear jagged. This 
is because the slope is effectively quantized. To understand this, consider two points 
with slope 0.1 between them. Recognizing that y,, y,, and x, are all integers in 
Equation (2.1), it follows that 


y,=y, +.) &-—%) 


Clearly, for y, to increase by one pixel on the screen, x, — x, must change by 11 
pixels in the horizontal direction. Thus the lines appear broken. 

Equations (2.1) and (2.2) are the key to developing techniques for plotting 
connecting line graphics in the IBM microcomputer context (or any other raster 
scanning device, for that matter). Figure 2.9a contains the flowchart for the connect- 
ing line program. Figure 2.9b illustrates the procedure CONNL2, which plots con- 
necting lies between the points (X0,Y0) and (X1,Y1) using as dummy variables 
(X2,Y2). The remaining variables (NCOUNT, SIGN, and M) are self-explanatory. 
The only complex feature of this routine, as it implements Equations (2.1) and (2.2), 
is the scaling mechanism. To prevent undue round-off the numerator of the slope is 
scaled up by a factor of 100. This is subsequently removed. The sign of the slope 
(SIGN) is calculated and used to demarcate the procedure based on positive versus 
negative values. The routine wdot is used to plot the connecting line. 

Figure 2.10 presents a program, slopeln.asm, that plots a connecting line be- 
tween the points 


(x, y,) = (25,25) 
and 


(x,, y,) = (275,175) 
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PRESERVE 
REGISTERS 


LOAD CONNL2 
DATA SEG. ADD. 


XO = XSTART 
X1 = XEND 
X2 = XSTART 


YO = YSTART 
Y1 = YEND 
Y2 = YSTART 


GENERATE NUMBER 
"CONNECTING" PTS. 
CALCULATE 
Y1- YO 
Y1- YO 


GREATER 
0? 


SCALE BY 100: SCALE BY 100: CALCULATE CALCULATE 
M = 100 (Y1 - YO) M = 100 (YO - Y1) YO + M (X2 - XO) YO - M (X2 - XO) 
NEGATIVE POSITIVE WRITE DOT AT 
SLOPE SLOPE X2 AND Y2 
CALCULATE INCREMENT X2 
M (X2 - XO) 
DIVIDE BY NUMBER x2 ¥ 
"CONNECTING" PTS. GREATER 


X1? 


N 


RETURN 
REGISTERS 
DIVIDE BY 100 TO DIVIDE BY 100 TO RETURN 
REMOVE SCALING REMOVE SCALING 


Figure 2.9a Functional flowchart for connecting line routine, conn12. 


75 


76 


Introductory OS/2 Assembler Programming Chap. 2 


PAGE 40,132 
TITLE CONNL2- CONNECT LINE AND PLOT (CONNL2.ASM) 


DESCRIPTION: This routine reads DX = 
(YSTART,YEND), BX = XSTART, and CX = XEND. 

It generates a connecting line between the 
points (XSTART,YSTART) and (XEND,YEND) and 
plots the points. The routine as part of the 
S/2 graphlib.lib 


Co ee ee) ee eT eT eT) 


a 
EXTRN YO:WORD, Y1: WORD, Y2: WORD, XO0:WORD, X1:WORD, X2: WORD 
EXTRN NCOUNT: WORD, SIGN: WORD,M: WORD, co1l:WORD, row: WORD 


EXTRN wdot: FAR 


, 

; 

; 

; Yo DW 6) 7Y start 

: Y2 DW ¢) *Y¥-value (dynamic) 

; Y1 DW ) 7Y¥ end 

; XO DW fe) 7X start 

: X2 DW (0) ;X-value (dynamic) 

; X1 DW fe) 7X end 

NCOUNT DW ) ;Number points in line 
: SIGN DW 0) ;Sign slope 

; M DW 0) ;Scaled partial slope 
7 ce ee cr cr re cree ee ee ee cre cree cre ee ee cee ee ee ee ee ee ee ee ee ee ee ee ee re ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 
CLINE SEGMENT PARA PUBLIC 'CODE' 


PUBLIC CONNL2 
CONNL2 PROC FAR 
ASSUME CS:CLINE 


PUSH DS 


PUSH AX 
PUSH BX 
PUSH CX 
PUSH DX 
PUSH DI 
PUSH SI 

;Load screen coordinates 
MOV AL, DH ;DH contains YSTART 
MOV AH,0 ;Clear top half AX 
MOV YO,AX ;Start Y-point 
MOV Y2,AX ;Also save YSTART in y 
MOV AL,DL ;DL contains YEND 
MOV AH,0 ;Clear top half AX 
MOV Y1,AX ;End Y-point 
MOV XO, BX ;Start X-point 
MOV X2,BX ;Save XSTART in x also 
MOV X1,CX ;End X-point 


Generate count index 


e =e Se Ne 


MOV AX,X1 ;Larger X-value in increment 
SUB AX,xX0 ;Calculate X-increment 
MOV NCOUNT, AX ;Number of X-points to connect 


;Generate slope 
;Clear upper numerator register 


;Begin calculation Y1 - YO for slope 


Figure 2.9b Program code for conn12, the connecting line routine. 
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JB ELSE1 


SIGN, AX 


AX, X2 
AX, XO 
DX, 0 
M 
NCOUNT 
CX, 100 
Ax cx 
JB ELSE2 
MOV DX,0 
DIV cx 
IMP IIF2 


MOV AX,0 
MOV BX,SIGN 


CMP BX,1 
JB ELSE3 


;Scale slope by 100 
;Clear upper multiplicand register 


;Slope in M 
;Sign negative for slope 
;Sign increment Y-axis points 


;Positive slope 
;Calculate (Y1 - YO) 
;Scale by 100 

;Clear upper register 


;Slope in M 
;Positive slope 
;Sign deecision Y-axis points 


;(X - XO) 
;Clear upper multiplicand register 
;Multiply by slope numerator 
;Begin completion slope calculation 
;Value corresponding to slope 1 
;Check for slope less 1 
;Jump slope less/= 1 
;Clear upper register 
;Remove scaling 


70 slope 


;Jump positive slope 


MOV BxX,YO ;Load Y-start value 
ADD AX, BX ;Add Mx(X-X0O) 


JMP IIF3 


MOV BX,YO ;Positive slope 
SUB BX,AX ;Generate YO - M x (X - XO) 
MOV AX, BX ;Save in AX 


MOV CX,X2 
MOV DX,AX 


MOV col,CX 
MOV row,DX 
CALL wdot 


INC X2 
MOV BX, X2 


CMP BX,X1 
JBE DO1 


CONNL2 


CLINE 
CONNL2 


Figure 2.9b 


, 


;X-position 
;Y¥-position 


e 
, 


swrite dot 


;0S/2 dot routine 


’ 


;Next point 


7;Ck X<= X1 


(Concluded) 
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TITLE SLOPELN - This program plots/prints sloped line (slopeln.asm) 


PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 


. 
, 


° 
’ 
e 
’ 
. 
’ 


PUBLIC 
PUBLIC 


NCOUNT 
SIGN 


DESCRIPTION: This program plots a sloped line in protected 
mode and hesitates using a keyboard delay. Graphics 
mode O5H is used to display the lines. 


prtscr:FAR,scr_1d:FAR,cls:FAR,c1SCGA: FAR, 1lineh: FAR,connl2:FAR 


include sysmac.inc 


-sall ;Suppresses macro lists 
GROUP data 


SEGMENT PARA STACK 'STACK'! 
db 256 dup('STACK  ') 
ENDS 


SEGMENT PARA PUBLIC 'DATA' 


in_buffer,bytesin,bytesout,in_bufferl,bytesinl 
in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
dev_mode,dev_rsv,MM,col1,N 

s,eight,eighty, four,shiftl,scr_buffer 
sixforty,N4,ddd,w,bl 


XX,XXxX,tr,lc,br,rc,no_line,blank,viohdl, PVBPtr1,physell,waitf 
dstat, four, two,col,dummy,MASK1,MASK11, row, eighty, address 
OFFSET1,y,xb,xe 


7x start 

7x end 

;dummy x 

ry start 

7y end 

;dummy y 

;number points in line 
7sign slope 

;scaled partial slope 


Figure 2.10 The program slopeln.asm, which plots on the screen a connecting 
line from (row,col) = (25,25) to (175,275). 
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Screen display variables 


&., 


viohdl 
result 
action 
tr 

le 

br 

ae! 
no_line 
blank 
CGAm 
lmodeE 
typeCGA 
COolCGA 
txtcCGA 
txtrCGA 
hrCGA 
vrCGA 
STDm 
1lmodes0 
types0 
colso 
txtc80o 
txtr8so 
hr8s0 
vr8s0 


kbd_buf 


label 
dw 
db 
dab 
dw 
dw 
dw 
dw 


db 


lkbd_buf dw 


lowait 
kbdhdl 
waitf 
dstat 


, 
PVBPtr1 
bufstl 
buflenl 
physell 
MASK1 
MASK11 
OFFSET1 
four 
XX 


dw 
equ 


equ 
db 


label 
dd 
dd 
dw 


db 
dw 
dw 
dw 
dw 
dw 
ab 
db 
dw 
daw 
dw 
aw 


dw 
dw 
dw 
daw 
dw 
dw 


dw 


00000111B 


2 
40 
25 
320 
200 


FAR 
12 


00000001B 


4 
80 
25 
720 
400 


80 


$-kbd_buf 


0 
fe) 


FAR 
OB8000H 
4000H 


VvvdO VN Ved > 


v 


° 


;Required video handle 
;Completion code 
;Terminates current thread 
;Top row screen clear 
;Left column screen clear 
;Bottom row screen clear 
;Right column screen clear 
;Number lines scrolled 
;Blank character pair 


;Video mode structure-CGA 
;Structure length 

;Mode identifier 

;Color option-Mode 5 

;text characters/line-ignore 
;text lines-ignore 
;horizontal resolution 
;vertical resolution 


;Video mode structure-80x25 
;Structure length 

;Mode identifier-Mode 3+ 
;Color option 

;text characters/line 

;text lines 

;horizontal resolution 
;vertical resolution 


;Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
;Returned status 


;Video buffer structure 
;Start physical address 
;Buffer length 

70S/2 screen buffer selector 


;PEL byte mask 
;Odd/even row mask 
;Odd row buffer offset 


;PEL modulo parameter 
780287 dummy "pop" 


;Output value 


7;rOW 
7column 
;Address screen dot 


;Box col parameter 
;Box row parameter 
7Start column 

7;End column 

;Start row 

7;End row 


Figure 2.10 (Continued) 
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80 


e 
’ 


in_buffer 


bytesin 

bytesout 
in_buffe 
bytesinl 
in_buffe 
bytesin2 
in_buffe 
bytesin3 
in_buffe 


, 
dev_name 
dev_hand 
dev_act 
dev_size 
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320 dup(0) 

dw 

(@) 
1BH,4BH, 64D, 01H 
4 

ODH, OAH 

2 

1BH, 41H, 08H 

3 

1BH, 32H 


p oll 

r2 

r3 

r4 
'LPT1',0 
6) 


6) 
fe) 


dev_attr 0 


dev_flag 
dev_mode 
dev_rsv 


N4 


coll 

bl 

N 

shiftl 

s 

ddd 
sixforty 
scr_buff 


- Owe =e se te Se 


00000001b 


0000000011000001b 


0 


= 
40H, 10H, 04H, 01H 


128,64,32,16,8,4,2,1 
320 dup(?) 
4 dup(?) 

ie 


6,4,2,0 
4 dup(?) 
? 

640 


er 16384 dup(0) 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dgroup 
PROC FAR 


call cls 

@VioSetMode CGAm,viohdl 

call cl1lsCGA 

@VioScrLock waitf,dstat,viohdl 
@VioGetPhysBuf PVBPtr1,viohdl 
push physell 

pop 

mov 

mov 

mov 

mov 


call connl2 


call scr_ld 


sprint buffer 

;CGA line 

;output count 

;printer setup 

;count bytes In_bufferl 
;LF/CR 

;in_buffer2 byte count 


;in_buffer3 byte count 


;name of printer device 
;device handle 


;Open File 

;reserved 

;pel mask 

;pin weights 
;column index-printer 


sprinter line 


;dup copies pel byte 


;temporary buffer--screen values 


;Clear screen 

;Set CGA Graphics mode 

7;Clear CGA screen 

;Lock screen context 

;Get physical buffer selector 
;Save selector 

;Load selector into extra segment 
;y-begin 

;y-end 

;x-begin 

;x-end 


;plot sloped line 


;loads the temporory buffer 


Figure 2.10 (Continued) 


;hdl private,deny none,w/o 
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@VioScrUnLock viohdl ;Unlock screen context 


@KbdStringIn kbd_buf,1lkbd_buf, iowait,kbdhdl ;hesitate 


@VioSetMode STDm,viohdl 780 x 25 alpha mode 

call prtscr ;prints temporary buffer 
@DosExit action,result ;Terminate process 

ENDP 


ENDS 
END 


Figure 2.10 (Concluded) 


This program calls conn12 to plot the line on the screen in the usual fashion. Note 
that the assembler is case insensitive. Next the print of the graphics screen is accom- 
plished. The nine variables needed by the connecting line module, conn12, are 
declared public and specified in the data segment of slopeln.asm. Figure 2.11 illus- 
trates the sloped-line output. 


Figure 2.11 Screen dump of sloped connecting line from slopeln.asm. 


Figure 2.12 illustrates a procedure bbox1.asm that plots a box based on gen- 
eral parameter inputs: (xb,yb) and (xe,ye) being the opposite corners of the box, 
with the first the upper left side and the second the lower right side. Figure 2.13 is 
the procedure linev, which is the corollary to lineh, and this procedure plots a ver- 
tical line. Figure 2.14 contains the contents of the library module GRAPHLIB.LIB. 
This module has all the graphics primitives and graphics printer screen dump 
modules. 
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PAGE 55,132 
TITLE BBOX1 - This is the boxx module (bboxl.asm) 


° 
t 


; DESCRIPTION: This module generates a box in protected 
; mode. It contains a procedures: boxx 
; 


y:WORD, yb: WORD, ye: WORD, x: WORD, xb: WORD, xe: WORD, lineh: FAR 
row:WORD,col:WORD,wdot: FAR, 1linev: FAR 


SEGMENT PARA PUBLIC 'CODE'! 
assume cs:cseg 
PUBLIC boxx 


PROC FAR 
xb = x-begin,xe = x-end,yb = y-begin,ye = y-end 


mov ax,yb *Top box line 

mov y,ax 

call lineh ;Draw top horizontal line 
mov ax,ye ;Bottom box line 

mov y,ax 

call lineh ;Draw bottom horizontal line 
mov ax,xb ;Left box line 

mov xX,ax 

call linev ;Draw left vertical line 
mov ax,xe ;Right box line 

mov xX,ax 

call linev ;Draw right vertical line 


ret 
ENDP 


boxx 


Figure 2.12 Routine bboxl.asm, which plots box and contains procedure boxx. 


Finally, Figure 2.15 illustrates a program that exercises boxx, the procedure for 
plotting a box based on the module bboxl.asm. This program is called bbox.asm 
and links as follows: 


fez\)] link bbox 


IBM Linker/2 Version 1.00 
Copyright(c) IBM Corporation 1987 
Copyright(c) Microsoft Corp 1983-1987. All rights reserved. 


Run File [BBOX.EXE]: 

List Files (NUL.MAP): 

Libraries [.LIB]: doscalls + graphlib 
Definitions File [NUL.DEF]: 
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PAGE 55,132 
TITLE LLINEV - This is the linev module (llinev.asm) 


DESCRIPTION: This module generates a vertical line in protected 
mode. It contains a procedure: linev 


y:WORD, yb: WORD, ye: WORD, Xx: WORD, xb: WORD, xe: WORD 
row: WORD, col:WORD,wdot: FAR 


SEGMENT PARA PUBLIC 'CODE'! 
assume cs:cseg 
PUBLIC linev 


PROC FAR 
= col position, yb = begin, ye = end 


ax,X ;Establish column for wdot 
col,ax 


ax,yb ;Establish start row 


row,ax 

push ax ;Save row value 

call wdot ;Write dot (col,row) 

pop ax ;Recall row 

inc ax ;Increment row 

cmp ax,ye ;Check end vertical line 
jle DO20 


ret 
ENDP 


ENDS 
END 


Figure 2.13 Vertical line procedure, linev. 


Offset: 00000010H and data 
Offset: 000000a0H and data 
Offset: OOOOO06bOH Code and data 


llinev Offset: OO0007b0H Code and data 
LINEV 


graphl Offset: 00000870H Code and data 
CLS CLSCGA LINEH 


Figure 2.14 Listing of GRAPHLIB.LIB, illustrating the screen graphics and 
screen print routines. 
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TITLE BBOX - This program plots/prints a box using modules (bbox.asm) 


. 
‘ 
° 
‘ 
° 
‘ 
° 
‘ 


PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 


. 
‘ 
. 
ul 
. 
Ul 
. 
‘ 


PUBLIC 
PUBLIC 
PUBLIC 


ee Se Ne Me Ne 


viohdl 
result 
action 
tr 

le 

br 

re 
no_line 
blank 
CGAm 
lmodeE 
typeCGA 
colCGA 
txtcCGA 
txtrCGA 
hrCGA 
vrCGA 


DESCRIPTION: This program plots a box in protected 
mode and hesitates using a keyboard delay. Graphics 
mode 05H is used to display the lines. 


prtscr:FAR,scr_1d:FAR,cls:FAR,C1SCGA: FAR, boxx: FAR 


include sysmac.inc 
-sall 
GROUP 


SEGMENT PARA STACK 
256 dup('STACK 


db 
ENDS 


SEGMENT PARA PUBLIC 


data 


;Suppresses macro lists 


in_buffer,bytesin,bytesout,in_bufferl,bytesinl 
in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 


dev_mode,dev_rsv,MM,col1,N 


s,eight,eighty, four,shift1l,scr_buffer 


sixforty,N4,ddd,w,bl 


ee es ss ss ss ss as ss ss se ee ee a a a a a a 


xX,xXXxX,tr,lc,br,rc,no_line,blank,viohdl,PVBPtr1,physell,waitf 
dstat, four, two,col,dummy,MASK1,MASK11,row,eighty,address 


OFFSET1,y,xb,xe,x,yb,ye 


FAR 

12 
00000111B 
2 

40 

25 

320 

200 


;Required video handle 
;Completion code 
;Terminates current thread 
;Top row screen clear 
;Left column screen clear 
;Bottom row screen clear 
;Right column screen clear 
;Number lines scrolled 
;Blank character pair 


;Video mode structure-CGA 
;Structure length 

;Mode identifier 

;Color option-Mode 5 

;text characters/line-ignore 
;text lines-ignore 
shorizontal resolution 
;vertical resolution 


Figure 2.15 Program that graphs box on screen and then dumps output to printer. 
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STDm label FAR 
lmodes0 dw 12 
types80 db 00000001B 


colso0 db 4 
txtc80 dw 80 
txtr8s0 dw 25 
hrs0 daw 720 
vr8s0 dw 400 


kbd_buf db 80 
lkbd_buf dw $-kbd_buf 
iowait dw 0 

kbdhdl equ e) 

waitf equ 

dstat db 


PVBPtr1 label FAR 
bufst1l dd OB8000H 
buflenl dd 4000H 
physell dw 


MASK1 db 
MASK11 dw 
OFFSET1 dw 
four dw 
XX dw 
dummy dw 
two db 
XXX db 
eighty dw 
row dw 
col dw 
address dw 


dw 
dw 
dw 
dw 
dw 


in_buffer 
bytesin dw 
bytesout ) 

in_bufferl 1BH, 4BH, 64D,01H 
bytesinl 4 

in_buffer2 ODH, OAH 
bytesin2 2 

in_buffer3 1BH,41H,08H 
bytesin3 3 

in_buffer4 1BH, 32H 


e 
’ 


dev_name ‘LPTL* , 0 
dev_hand e) 
dev_act ce) 
dev_size 0 
dev_attr fe) 


320 dup(0) 
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;Video mode structure-80x25 
;Structure length 

;Mode identifier-Mode 3+ 
;Color option 

;text characters/line 

;text lines 

shorizontal resolution 
;vertical resolution 


;Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
;Returned status 


;Video buffer structure 
;Start physical address 
;Buffer length 

7;0S/2 screen buffer selector 


;PEL byte mask 
;Odd/even row mask 
;Odd row buffer offset 


;PEL modulo parameter 
780287 dummy "pop" 


;Output value 


;rOwW 
;column 
;Address screen dot 


;Box col parameter 
;Box row parameter 
;Start column 

7;End column 

;Start row 


;print buffer 

7;CGA line 

;output count 

;printer setup 

;count bytes In_bufferl 
;LF/CR 

;in_buffer2 byte count 


;in_buffer3 byte count 


;name of printer device 
;device handle 


e 
’ 


’ 
° 
’ 


Figure 2.15 (Continued) 
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dev_flag dw 00000001b ;Open File 

dev_mode dw 0000000011000001b shdl private,deny none,w/o 
dev_rsv dd fe) ;reserved 

N4 dw 7 

MM db 40H,10H,04H,01H ;pel mask 

W db 128,64,32,16,8,4,2,1 ;pin weights 
cols db 320 dup(?) ;column index-printer 
bl db 4 dup(?) 

N dw ? sprinter line 

shiftl db 6,4,2,0 

s db 4 dup(?) ;dup copies pel byte 
ddd dw ? 

sixforty dw 640 


scr_buffer 16384 dup(0) ;temporary buffer--screen values 


SEGMENT PARA PUBLIC 'CODE! 
assume cs:cseg,ds:dgroup 
PROC FAR 


call cls ;Clear screen 


@VioSetMode CGAm,viohdl ;Set CGA Graphics mode 


call clsCGA ;Clear CGA screen 


@VioScrLock waitf,dstat,viohdl ;Lock screen context 


@VioGetPhysBuf PVBPtri1,viohdl ;Get physical buffer selector 
push physell ;Save selector 
pop es ;Load selector into extra segment 


call boxx ;generate box 


call scr_lda ;loads the temporory buffer 


@VioScrUnLock viohdl Unlock screen context 


@KbdStringIn kbd_buf,1lkbd_buf,iowait,kbdhdl shesitate 


@VioSetMode STDm,viohdl 780 x 25 alpha mode 


call prtscr ;prints temporary buffer 


@DosExit action,result ;Terminate process 


ENDP 
CSEG ENDS 
END 


Figure 2.15 (Concluded) 


Figure 2.16 presents the output for the box. It assumes the following corner values 
based on the data segment specification: 


(xb, yb) = (75,25) 
and 
(xe, ye) = (150,175) 


It is important to recognize that the method for accessing the OS/2 physical 
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display buffer is initially cumbersome since the display context must first be locked. 
Good programming practice, however, would implement this step only once during 
execution of a given process or thread. Then full-screen DMA is permitted. Al- 
though the advantage of using multitasked display contexts under OS/2, for example, 
is lost, the programmer still has access to the very large address space provided by 
OS/2. 


Att be reeeeest eeeeee tt memes 1 eeremeness pemmeecennmeceseeomnenes tomes. 


Figure 2.16 Box screen print from 
| bbox.asm (Figure 2.15). 


It is the benefits of multitasking and memory access that highlight OS/2’s 
attributes. If animation or rapid update of the screen context is needed, the applica- 
tion must be structured to maximize its screen access while continuing to take 
advantage of other task-sharing arrangements and memory requirements in a multi- 
tasking environment. 


2.4 SOFTWARE DESIGN 


No introductory programming discussion would be complete without mentioning 
software design techniques. Three principals come to mind: 


1. Modular code 
2. Top-down design 
3. Structured programming 


These form the foundation for developing optimized computer programs [6,7]. 

We have seen examples of the use of modular code in the examples presented 
so far. Basically, programs have been developed on existing independent smaller 
modules (such as prtscr, bbox, lineh, linev, ...).These modules may be linked as 
separately assembled (in this case) routines or appear in libraries. The entire notion 
of the API embodies a modular approach to handling system services. 

Top-down design is somewhat straightforward and starts with a high-level 
statement of the problem to be solved. From this approach a flowchart can be 
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developed or, alternatively, a written language rendition of what the program will 
accomplish. These two approaches lead naturally into program development. It is not 
the intention of this book to teach design fundamentals; hence we will usually 
confine ourselves to the actual code implemented in each instance. It is assumed that 
the reader can generate design artifacts in either flowchart format or pseudo-code. 
General guidelines tend to suggest flowcharts when program dynamics are particu- 
larly important. As size becomes a factor, the interfaces tend to dominate program- 
ming considerations and pseudo-code becomes desirable. 

Finally, we mentioned structured programming. Assembler is intrinsically 
unstructured because of the conditional and unconditional jump instructions. Guide- 
lines exist, however, that permit structured techniques with assembly language and 
very understandable code results [8,9]. As Martin points out (reference 6), an excel- 
lent starting point for top-down design is the development of a structure chart that 
links each module in static fashion. Structured code accomplishes similar design 
tasks by forcing the designer to limit access to each module. Parameter passing be- 
comes very orderly and the variables used within a module are maintained locally 
except for those passed externally. The flow of execution is orderly and downward 
avoiding unrestrained jumps within the code. In BASIC and C, for example, the 
goto instruction is avoided. Entry points are accessed in traceable fashion. We will 
discuss C programming in a subsequent chapter, and the syntax of the language 
naturally lends itself to structured code. In assembly language the use of syntax of 
the form 


cmp ax,parm 
jle ELSE1 
jmp IIF1 
ELSE1: 


LiFis 


implements the familiar IF...THEN...ELSE. .. structure. Note the use of uncondi- 
tional jumps to do this. The reader must, of course, recognize that any decision logic 
in a higher-level language results in conditional or unconditional jumps at the assem- 
bler or machine code level. The fact that we can structure such an assembler, how- 
ever, yields significant improvement in clarity and understanding. 


2.5 SUMMARY 


The goal of this chapter was to introduce assembler programming for OS/2 with a 
particular emphasis on the techniques needed to access the Application Program 
Interface. It was the use API services, as demonstrated through specific examples, 
that we intended to emphasize. We developed examples of printer and display ac- 
cess within the API context. A set of program modules was written that allow the 
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user to obtain a screen dump for the CGA graphics screen. This is similar to the fa- 
miliar DOS GRAPHICS.COM routine except that they are not terminate and stay 
resident (TSR) programs but must be called as active program modules. Similarly, 
they must be linked to the user program either as stand-alone modules or from the 
library GRAPHLIB.LIB established in the chapter. 

It is clear from the chapter that the API must be accessed in more structured 
fashion than the normal interrupt call, where free access to the general-purpose 
registers is permitted. The advantages of accessing memory above 1 MB are pro- 
vided by OS/2, and the API architecture is a consequence of this process. Also, the 
features of multitasking require a Protected Mode structure. Hence these two aspects 
of programming with Intel hardware such as the 80286 cause programming struc- 
tures such as the API to become essential. This, then, is the justification for learn- 
ing the API and using OS/2. Eventually, when the programming applications reach 
a size where only OS/2 can offer the memory allocation or severe multitasking 
constraints are placed on the user, DOS will inevitably be replaced by OS/2. Thus 
the programming techniques of this chapter are the beginning approaches to learn- 
ing how to manage IBM’s next-generation microcomputer operating system. 
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PROBLEMS 


2.1 Output of a character in the printer graphics mode causes the pins in the print head to 
fire, depending on the value of the character (0-255). Which pins fire for the Epson 
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Lode 
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FX-85 for the following values: (a) 174; (b) 203; (c) 85? Assume that the top pin 
is number 8. 


The macro call 


@VioGetPhysBuf PVBPrtl,rsv 


is an example of the OS/2 access to the physical buffer selector (contained in the 


structure PVBPrt1). If the calling sequence for VIOGETPHYSBUF, the API routine, is 
given by 


EXTRN VioGetPhysBuf:FAR 


PUSH@ Label Data structure (PVBPrtl) 
PUSH word reserved 
CALL VIOGETPHYSBUF 


write a macro to achieve the call indicated above. Use the macros defined in the chap- 
ter: @define, @pushw, and @pushs. 


2.3 As in Problem 2.2, if the macro @VioScrLock has the calling sequence 


2.4 


Leo 
2.6 


Bol 


2.8 
2ut 


EXTRN VioScrLock:FAR 


PUSH word waitflag 
PUSH@ BYTE status 
PUSH word handle 
CALL VIOSCRLOCK 


define a macro to achieve the call using the macros defined in the chapter: @define, 
@pushw, and @pushs. 


The EGA graphics on the IBM Monochrome Display is a 640 x 350 graphics mode 
(ModeHexF). The first eight pixels on the screen are defined by the contents of 
memory in location AOOOOH. The screen buffer is mapped into two planes (Map0 and 
Map2). Assume that only Map0 is specified (a default value of white on the normal 
background) and this subtends the first 28,000 bytes at AOQOOOH. If each bit corre- 
sponds to O (black) or 1(white), what changes would be needed to the programs in 
this chapter to allow the code to properly access the EGA screen buffer? 


Write a code fragment that generates the note C (5000 Hz) for 1 second. 


Write a code fragment that plots a straight line from (row, col) = (25,75) to (165,235). 
Use conn12. 


Write a code fragment that beeps the speaker for 5 seconds (1000 Hz) following the 
Striking of a key on the keyboard. 

Is it possible to program OS/2 using simply the OS/2 supplied by IBM? Explain. 
When accessing the physical screen buffer, a segment selector was obtained using 
VioGetPhysBuf. This selector was pushed and popped into es, the extra segment regis- 


ter. Screen buffer address locations were then accessed using, for example, a segment 
override: 


es: [bp] 
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2.10 


Pee lidl. 


100 


Dosh se 


Zsko 


2.14 


Oe be 


where bp was the offset in the screen buffer. What key assumption permits this ad- 
dressing scheme, and how is it implemented? 


Structure labels used by the API Toolkit services represent FAR or NEAR loca- 
tions? Why? 

A structure chart lays out the hierarchy of control for a program. Consider a struc- 
ture chart that calculates a Gaussian random array and plots it on the screen. What 
deficiency exists in this presentation assuming that the functional characteristics of 
each block are accurate and complete? 


000 


PLOT RANDOM 
ARRAY 


200 
INPUT GENERATE 
SEED ARRAY 


220 230 


210 


SET GENERATE PRODUCE SCREEN 


RANDOM GAUSSIAN PRESENTATION 


NUMBER 
SCALING 


In ordinary printing the line spacing is 1/6 inch. The command 
ESC A (n) 


produces a line spacing of n/72 of an inch. What command is needed in prtscr to 
return the printer to normal spacing? 


A key aspect of OS/2 programming is that the device driver Interrupt Service Rou- 
tine (ISR) is the only type of program authorized to receive hardware interrupts. 
Each device driver can have an ISR to process the device interrupts. When the in- 
terrupt routine is given control, it has access to the GDT but not any specific LDT. 
The routines must rely on the DevHIp services to access application buffers. These 
routines run at the highest level of the kernel mode. Are they preemptable by OS/2 
task switches? Explain. 


Explain why scr_ld must be called with the screen locked and why prtscr should not 
be called with the screen locked. 


When drawing a line segment from 


(row,column) = (10,10) 


(row,column) = (20,110) 
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how many small straight-line raster segments will be visible in the actual plotted 
line? 

DosExitCritSec executes after DosEnterCritSec and reenables thread switching for 
the current process. A count of the number of outstanding DosEnterCritSec requests 
is maintained. When are these functions likely to be used? 


Observe that DosExit is used only at the conclusion of the main calling module. 
What are the criteria for this exit, and how should other modules be terminated? 


3 Memory Management 
and Multitasking 
with Assembler 


OS/2 is first and foremost a multitasking and memory management operating sys- 
tem. It was developed around the Intel 80286 Protected Mode hardware implemen- 
tation and employs the features of this hardware, such as segment selector protection 
mechanisms, to achieve multitasking operation. The goal of this chapter is to ac- 
quaint the reader with these features of OS/2 in an assembler programming environ- 
ment. 


3.1 MEMORY MANAGEMENT AND MULTITASKING 


Memory management and multitasking represent siatic and dynamic aspects of 
programming and are intimately tied to the protection mechanisms of the 80286 for 
the OS/2 environment. The 80286 has three basic protection aspects: 


1. Isolation of system software from end-user applications 
2. Isolation of users from each other 
3. Data-type checking 


In terms of a ringed picture, the 80286 provides a four-level increasingly privileged 
protection mechanism that isolates applications from the various layers of system 
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software. To understand protection on the 80286, we must begin with its basic parts: 
segments and tasks. It is interesting that this division leads naturally into memory 
management and multitasking. Both are interrelated as pointed out above and yield 
a full Protected Mode picture. 


The following illustrates a complete 80286, descriptor cache register (as we 
have seen in Chapter 1): 


Selectors 


Segment Register Access Segment Base Segment Size 
Rights Address 


Program Visible | Program Invisible 
(loaded by program) (loaded by CPU) 


The important features of this register that should be recognized are that in the 
invisible portion of the register both the access rights byte (with segment type and 
privilege level) and size are used to determine protection priority and the segment 
base address confirms that the selected segment is valid. Hence a hardware imple- 
mentation is used to restrict segment access. 

By way of review, dynamically each task consists of up to four active seg- 
ments (with segment registers CS, SS, DS, and ES), as we have seen. The method- 
ology above is used to control segment protection, and since the hardware can 
dynamically check protection data, this extends into the task realm. The protection 
data are used at two different times dynamically: upon loading a segment register 
and upon each reference to the selected segment. Each task can address up to a gi- 
gabyte (2*-2 segments of up to 65,536 bytes) of virtual memory defined by the 
task’s LDT and the system GDT. The task’s private address space (LDT) can oc- 
cupy up to one-half this memory. The rest is defined by the GDT. The CPU has a 
set of base and limit registers that point to the GDT and the LDT of the currently 
running task. These registers exist for CS, SS, DS, and ES as defined for the task. 
An active task can only load selectors that reference segments defined by its LDT 
descriptors or the GDT. Since a task cannot reference descriptors in other LDTs, 
protection violations cannot occur. 

All descriptor tables have a limit used by the protection hardware to ensure 
that correct address space size allocation occurs. This ensures that separation of tasks 
takes place. The third ingredient in this protection mechanism is the implementation 
of privilege-level checks based on the access rights byte assigned privilege level. 
The 80286 privilege-levels are: 


1. Level 0: The kernel (most trusted) includes memory management, task isola- 
tion, multitasking, intertask communication, and I/O resource control. 


2. Level 1: System Services (next most trusted level) provides high-level func- 
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tions such as file access scheduling, character I/O, data communications, and 
resource allocation. 


3. Level 2: Custom Extensions (third most trusted level) allows standard sys 
tem software to be customized: database managers, logical file access services, 
and so on. 


4. Level 3: Applications (least trusted) include normal programming environ- 
ment. 


It is important to recognize the protection intrinsic to this hierarchy. Functions 
catastrophic to system failure are more tightly protected. This ensures that tasking 
can continue to execute in the event of single-task failures. Descriptor privilege, 
including code segment privilege, is assigned when the descriptor is created. The 
system designer assigns privilege directly when the system is constructed or indi- 
rectly using a loader. This is how OS/2 functions. OS/2 was designed with appro- 
priate access byte values associated with the kernel and each system service seg- 
ment. The linker (and loader) assign privilege at a higher level (less trusted) to all 
applications software subsequently developed. The programmer does not normally 
have access to this privilege specification, and we will not tamper with this mecha- 
nism. These are, however, the techniques used by OS/2 to provide memory manage- 
ment and multitasking protection (segment base checking, limit checks, and access 
rights byte validation). 

Task privilege is dynamic and can change only when control transfers from 
one code segment to another. Descriptor privilege, including code segment privilege, 
is assigned when the descriptor is created. Clearly, as a task executes, the privilege 
level of the task must correspond to that of the code segment currently executing. 
Hence such privilege is dynamic. Several general rules apply: 


1. Data access is restricted to those segments whose privilege level is the same 
or less privileged (numerically greater) than the current privilege level (CPL). 


2. Direct code access is restricted to code segments of equal privilege. 
3. A gate is required for access to code at more privileged levels. 


A gate is a control descriptor consisting of four words. It is used to redirect execu- 
tion to a different segment at a more privileged level. These call gate descriptors are 
used by control instructions (call and jump instructions) in much the same fashion 
as segment descriptors are used during normal transfer of code segments at the same 
level. 

Above, we have briefly examined the background for memory management 
and multitasking. Here the emphasis has been on hardware features and privileged 
access (and summarizes the discussion of protection in Chapter 1). It is important 
to recognize that these are hardware features in the Intel chips. Multitasking and 
dynamic memory allocation are particularly well suited to the Intel segmented 
memory [1]. CPUs with less protection, such as simple system and user privilege, 
are less ideally suited for protection during multitasking [2]. 
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3.2 MEMORY MANAGEMENT ACTIVITIES 


This section is intended to illustrate simple programming concepts related to 
memory management. Under OS/2 the management of memory is accomplished 
dynamically using the API calls. These calls all execute primarily at level 0 and 
permit memory management of higher-level code, such as applications developed by 
the user. 


3.2.1 Creating and Accessing Memory Segments 


The simplest activity associated with memory management is the creation, access, 
and destruction of a memory segment. The code associated with accomplishing this 
action is represented as follows: 


msize dw (size in bytes of segment) 
msell dw ? 
mflag dw 0000000000000111B ;sharable, discardable 


@DosAllocSeg msize, msell, mflag 


@DosFreeSeg msell 


Figure 3.1 illustrates the program twolnm.asm, a modified version of the 
module twoln.asm. This program creates a temporary buffer in place of scr_buffer 
(the buffer used earlier) and uses the representative code shown above to accom- 
plish this action. The parameter msize has been specified to be 16,384 bytes, the 
buffer size for the screen buffer. A selector, msell, is obtained from the call to 
@DosAllocSeg, and the specified flag indicates that the selector’s segment is shar- 
able among code segments other than the one creating the segment, and may be dis- 
carded. Finally, once the print screen function is performed, the segment is discarded 
using the @DosFreeSeg call. 

Figure 3.2 contains the code for scr_ldm, a modified version of scr_ld. Since 
the physical screen buffer segment must be accessed using ES (based on selector 

_ physell) and the newly created temporary buffer (using the selector msel1), the extra 
segment must share its usage between these two selected segments. To accomplish 
this, es is pushed after each reference to the physical screen buffer, loaded with 
msell, and then used to access the temporary buffer. Following this action, the 
physical screen buffer is popped back into es and another access of this buffer 
accomplished. Intermediate buffer values are passed using AX. (Note: We use upper 
and lowercase references to the 80286 registers in interchangeable fashion.) 

Figure 3.3 provides the program for the module prtscrm, a modified version of 
prtscr. The only change in this routine is the earlier access to scr_buffer: 
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TITLE TWOLNM - This program plots/prints 2 lines (twolnm.asm) 


DESCRIPTION: This program plots two lines in protected 
mode and hesitates using a keyboard delay. Graphics 
mode 05H is used to display the lines. 

The routine uses DYNAMIC MEMORY ALLOCATION. 


prtscrm: FAR,scr_ldm:FAR,cls:FAR,c1sSCGA: FAR, lineh: FAR 


include sysmac.inc 


-sall ;Suppresses macro lists 
GROUP data 


SEGMENT PARA STACK 'STACK! 
db 256 dup('STACK ') 
ENDS 


SEGMENT PARA PUBLIC 'DATA' 


PUBLIC in_buffer,bytesin,bytesout,in_bufferl,bytesinl 
PUBLIC in_buffer2,bytesin2,in_buffer3,bytesin3,in_buffer4 
PUBLIC dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
PUBLIC dev_mode,dev_rsv,MM,col1,N 

PUBLIC s,eight,eighty,four,shift1l 

PUBLIC sixforty,N4,ddd,w,bl 


PUBLIC xx,xxx,tr,lc,br,rc,no_line,blank,viohdl, PVBPtr1,physell,waitf 
PUBLIC dstat,four,two,col,dummy,MASK1,MASK11,row,eighty,address 
PUBLIC OFFSET1,y,xb,xe 


PUBLIC 


viohdl ;Required video handle 
result ;Completion code 

action ;Terminates current thread 
tx dw ;Top row screen clear 

IG dw ;Left column screen clear 
br dw ;Bottom row screen clear 
re dw ;Right column screen clear 
no_line dw ;Number lines scrolled 
blank dw ;Blank character pair 


CGAm label ;Video mode structure-CGA 
lmodeE dw ;Structure length 
typeCGA db 00000111B ;Mode identifier 


Figure 3.1 The program twolnm.asm (a modified version of twoln.asm), which 


creates a buffer for the screen memory. 
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colCGA db 
txtcCGA dw 
txtrCGA dw 
hrCGA dw 
vrCGA daw 


STDm label 
lmodesg0 dw 
types0 db 
colso ab 
txtc80 dw 
txtr8s0 dw 
hrs0 dw 
vr8s0 dw 


kbd_buf db 
lkbd_buf dw 
lowait 
kbdhdl 


waitf 
dstat 


PVBPtr1 
bufst1l 

buflenl 
physell 


’ 
MASK1 
MASK11 
OFFSET1 
four 

XX 
dummy 
two 

XXX 
eighty 
row 

col 
address 


=e Se Se Se Me Ne 


in_buffer 
bytesin dw 
bytesout 
in_buffer1l 
bytesinl 
in_buffer2 
bytesin2 
in_buffer3 
bytesin3 
in_buffer4 


12 


00000001B 


4 
80 
25 
720 
400 


80 


$-kbd_buf 


0) 
fe) 


1 
? 
FAR 


OB8000H 
4000H 


4 
£ 
Ps 
2 
? 
8 
fs 
i 
£ 


320 dup(0) 


0) 


1BH, 4BH,64D,01H 


4 
ODH, OAH 
2 


1BH, 41H, 08H 


3 
1BH, 32H 


;Color option-Mode 5 

;text characters/line-ignore 
;text lines-ignore 
;horizontal resolution 
;vertical resolution 


;Video mode structure-80x25 
;Structure length 

;Mode identifier-Mode 3+ 
;Color option 

;text characters/line 

;text lines 

shorizontal resolution 
;vertical resolution 


;Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
;Returned status 


;Video buffer structure 
;Start physical address 
;Buffer length 

;0S/2 screen buffer selector 


;PEL byte mask 
;Odd/even row mask 
;Odd row buffer offset 


;PEL modulo parameter 
780287 dummy "pop" 


;Output value 


;rOw 
7;column 
;Address screen dot 


;Box col parameter 
;BOox row parameter 
;Start column 

7End column 

;Start row 


;print buffer 

;CGA line 

;output count 

;printer setup 

;count bytes In_bufferl 
;LF/CR 

;in_buffer2 byte count 


;in_buffer3 byte count 


Figure 3.1 (Continued) 
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dev_name 
dev_hand 
dev_act 
dev_size 
dev_attr 
dev_flag 
dev_mode 
dev_rsv ce) 


00000001b 


N4 2 
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0000000011000001b 
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;name of printer device 
;device handle 


° 
t 
e 
’ 
° 
’ 
e 
t 


Open File 
shdl private,deny none,w/o 
;reserved 


MM 40H,10H,04H,01H ;pel mask 


w 128, 64,32,16,8,4,2,1 


coll 320 dup(?) 
bl 4 dup(?) 

N ? 

shiftl 6,4,2,0 
s 4 dup(?) 
ddd z 
sixforty 


‘ 
° 
’ 
’ 
. 
’ 


0000000000000111 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dgroup 
PROC FAR 


call cls 
@VioSetMode CGAm,viohdl 


call clsCGA 


@VioScrLock waitf,dstat,viohdl 


@VioGetPhysBuf PVBPtr1,viohdl 
push physell 
pop es 


mov ax,0O 
Mov y,ax 
call lineh 
mov ax,100 
MOv y,ax 
call lineh 


@DosAllocSeg msize,msell1,mflag 
call scr_ldm 


@VioScrUnLock viohdl 


@KbdStringiIn kbd_buf,1lkbd_buf, iowait,kbdhdl 


@VioSetMode STDm,viohdl 


call prtscrm 


B ;segment sharable, 


;pin weights 
;column index-printer 


;printer line 


;dup copies pel byte 


;temporary buffer-screen values 
s;allocated selector 
discardable 


;Clear screen 
;Set CGA Graphics mode 


;Clear CGA screen 


;Lock screen context 
;Get physical buffer selector 


;Save selector 
;Load selector into extra segment 


;Draw line 


;draw second line 

;allocate temporary buffer 
;loads the temporory buffer 
;Unlock screen context 
;hesitate 
780 x 25 alpha mode 


;prints temporary buffer 


Figure 3.1 (Continued) 
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@DosFreeSeg msell ;free allocated space 


@DosExit action,result ;Terminate process 


ENDP 
ENDS 
END O0S21 


Figure 3.1 (Concluded) 
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TITLE SCRLDM -- This routine loads the screen print buffer (scrldm.asm) 


DESCRIPTION: This routine accompanies prtscr to load 

and print the screen in 320 x 200 mode. 

The prtscr buffers are assumed loaded. This is an OS/2 

routine. This routine uses DYNAMIC MEMORY ALLOCATION through msell. 


EE] ~e we se se se Me 


mseli:WORD 
-sall 


SEGMENT PARA PUBLIC 'CODE' 
PUBLIC scr_ldm 

PROC FAR 

ASSUME CS:CSEG 


e 
’ 


mov cx,100 ino. of raster pairs 
mov di,O ;index to screen buffer 
mov si,O ;index to dummy array 


push cx 
mov cx,80 ;raster row length 


mov al,es: [di] ;load even row physical buffer 
mov ah,es: [di+2000H] ;0dd row physical buffer 


push es 

mov es,msell 

mov es:[si],al ;load even rows 
mov es:[{si+80],ah ;odd rows 

pop es 


inc si 

inc di 

loop DO56 

add si,80 ;skip to next double 
pop cx 

loop DO55 


ret 
ENDP 
ENDS 
END 


Figure 3.2 The modified scrld.asm (scrldm.asm) used with the program 
wolnm.asm. 


Sec. 3.2 Memory Management Activities 101 


55,132 
prtscrm - print screen (prtscrm.asm) 


DESCRIPTION: This routine prints the screen in 
320 x 200 CGA mode. This routine uses DYNAMIC 
MEMORY ALLOCATION. This routine needs the 
following data items in the calling routine 
data segment: 


in_buffer 320 dup(0) 
bytesin 320 

bytesout (e) 

in_bufferl 1BH, 4BH,64D, 01H 
bytesinl 4 

in_buffer2 ODH, OAH 
bytesin2 2 

in_buffer3 1BH,41H,08H 
bytesin3 3 

in_buffer4 1BH, 32H 


dev_name "LPT1" , 0 

dev_hand 0 

dev_act 0 

dev_size 0 

dev_attr ) 

dev_flag 00000001b 
dev_mode 0000000011000001b 
dev_rsv dd 


MM 40H, 10H, 04H, 01H 

w 128,64,32,16,8,4,2,1 
coll 320 dup(?) 

N ? 

N4 | 

s 4 dup(?) 
shiftl 6,4,2,0 
eight 8 
eighty 80 

bl 

four 

ddd 

sixforty 


. 
’ 
. 
’ 
. 
’ 
° 
’ 
e 
’ 
. 
’ 
e 
’ 
e 
’ 
. 
’ 
e 
, 
e 
’ 
° 
’ 
° 
, 
. 
‘ 
° 
’ 
. 
’ 
° 
’ 
e 
’ 
. 
’ 
e 
' 
. 
’ 
e 
‘ 
° 
’ 
e 
, 
° 
‘ 
e 
’ 
e 
' 
° 
, 
. 
‘ 
e 
’ 
. 
, 
e 
, 
e 
' 
e. 
, 
° 
’ 
° 
, 
e 
/ 
e 
, 
e 
, 
. 
, 
e 
, 
e 
’ 
e 


’ 

EXTRN MM: BYTE,w: BYTE, col1: BYTE 

EXTRN in_buffer: BYTE, in_bufferl:BYTE,in_buffer2: BYTE 
EXTRN in_buffer3:BYTE,in_buffer4:BYTE 

EXTRN bytesin:WORD, bytesin1l:WORD, bytesin2:WORD, bytesin3:WORD 
EXTRN bytesout:WORD,dev_name: BYTE,dev_hand: WORD 

EXTRN dev_act:WORD,dev_size:DWORD,dev_attr: WORD 

EXTRN dev_flag:WORD,dev_mode:WORD,dev_rsv: DWORD 

EXTRN N:WORD,N4:WORD 

EXTRN eighty:WORD, eight: WORD, four:WORD,s:BYTE,shift1: BYTE 
EXTRN ddd:WORD,b1:BYTE,sixforty:WORD,msel1:WORD 


’ 
IF1 

include sysmac.inc 
ENDIF 


e 
’ 


-sall 


CSEG SEGMENT PARA PUBLIC 'CODE' 
PUBLIC prtscrm 


Figure 3.3 The modificd prtscr.asm (prtscm.asm) used with the program 
twolnm.asm. 
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prtscrm PROC FAR 

ASSUME CS:CSEG 

;open device 

@DosOpen dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag,dev_mode,dev_rsv 

cmp ax,0 

je ELSE1 

SExit 

ret 


;initialize device 
@DosWrite dev_hand,in_buffer3,bytesin3,bytesout 
@DosWrite dev_hand,in_buffer4,bytesin2,bytesout 


, 
mov dax,25 ;number print lines(+1) 
mov si,0O ;index to 8 row block 


push dx ;preserve dx 


push si ;preserve block count 
mov ax,Ssi 

mul sixforty 7640 block size 

mov N,ax ;Save in N 


e 
’ 


call ldarray 
; 
mov di,O sinitialize 320 column counter 
mov cx,80 ;count of column bytes 


mov al,coli[di] ;column 1 from byte 
mov in_buffer[di],al ;load print buffer 

mov al,coli[di+1]} ;column 2 from byte 
mov in_buffer[di+1],al ;load print buffer 

mov al,colli[di+2] ;column 3 from byte 
mov in_buffer[(di+2],al ;load print buffer 

mov al,coll1[di+3] ;column 4 from byte 
mov in_buffer[di+3],al ;load print buffer 

add di,four ;increment column index 
loop LOOP2 


;write print row 
@DosWrite dev_hand,in_bufferl,bytesin1,bytesout 
@DosWrite dev_hand,in_buffer,bytesin, bytesout 
@DosWrite dev_hand,in_buffer2,bytesin2,bytesout 


’ 


pop si ;recall block count 

pop dx ;recall print line count 
dec dx ;decrement count 

inc si ;increase block count 
cmp dx,0 ;check 25 lines printed 
jle DII1 


jmp LOOP1 


@DosClose dev_hand 
ret 
endp 


;close print device 


PROC NEAR 


N is the printer row # - 640 byte intervals [0,24] 


=e Se Se Se Ne 


MM[O] = 40H,...,MM[3] = 01H (pel mask) 

w(0] = 128,w[1] = 64,...,w[7] =1 

mov si,0O ;column count initialization 
mov cx,320 7320 columns 


mov al,O ;clear print buffer 
mov coli[si],al 
inc si ;increment column count 


loop DO110 


Figure 3.3. (Continued) 
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si,0O 
N4,Si 
ax,80 


mov di,O 
mov ddd,di 
mov cx,8 


push cx 
mov bp,ddd 
add bp,N 


push es 

push msell 

pop es 

mov al,es: [bp+si] 
pop es 


mov s[0],al 
mov s[{1],al 
mov s[2],al 
mov s[3],al 


and al,MM[0] 
mov cl,shift1[0] 
shr al,¢l 

mov ah,O 

mul w[di] 

mov b1[0],al 


mov al,s[1] 

and al,MM[1] 
mov cl,shift1[1] 
shr al,cl 

mov ah,0O 

mul w[di} 

mov bl1[{1],al 


mov al,s[2] 

and al,MM[2] 

mov cl,shift1[2] 
shr al,cl 

mov ah,0O 

mul w[di] 

mov b1[2],al 


mov al,s[3] 

and al,MM[3] 

mov cl,shift1[3] 
shr al,cl 

mov ah,0O 

mul w[{di] 

mov b1[3],al 


push bx 

mov bx,N4 

mov al,b1[0] 

add coll[bx],al 
mov al,bl[1]} 

add coll[{bx+1],al 
mov al,b1[2] 

add coll[bxt2],al 
mov al,b1[3] 

add coll[bx+3],al 
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’ 


;index into 80 bytes/row 
7;N4 = row byte block count 
;counter - row bytes 


e 
’ 


;raster row counter (1 of 8) 
780 block counter 
raster row counter 


;preserve row count 
;bp = # 80 byte blocks 
;add printer line count 


sload address screen buffer 
74 pel bytes 


71st copy 
72nd copy 
;3rd copy 
74th copy 


e 
, 


;1lst pel mask 

;load 1st pel shift 
;shift right 

;clear upper 

;multiply by weight (row) 
;Save ist printer column 


;load 2nd pel 

;mask 2nd pel 

;load 2nd pel shift 
;shift right 

;clear upper 

;multiply by weight (row) 
;save 2nd printer column 
;load 3rd pel 

;mask 3rd pel 

s;load 3rd pel shift 
;shift right 

;clear upper 

;multiply by weight (row) 
;save 3rd printer column 


;load 4th pel 

;mask 4th pel 

;load 4th pel shift 

shift Tight 

;clear upper 

;multiply by weight (row) 
;save 4th printer column 
;preserve bx 

;counter into print buffer 
;load column N4 


;load column N4+1 
s;load column N4+2 


s;load column N4+3 


Figure 3.3. (Continued) 
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pop bx 


pop cx ;recall print block row index 
inc di ;increase print block row counter 
add ddd,80 ;increase byte count 
dec cx ;decrease row bound 
cmp cx,0 
jle DO133 
jmp DO112 


add N4,4 ;add 4 columns to index 
dec dx ;decrement row bytes 
inc si ;increase screen buffer index 
cmp dax,0 
jle DII2 
jmp DO111 
DII2: 
ret 
ldarray ENDP 


CSEG ENDS 
END 


Figure 3.3. (Concluded) 


push bx 

lea bx,scr_buffer[0] 
add bp,bx 

mov al,ds:[bp+si] 
pop bx 


This now reads 


push es 

push msell 

pop es 

mov al,es:[bp+si] 
pop es 


where the same buffer now appears starting at es:0000. 

Figures 3.1 through 3.3 represent simple examples of how to create and use a 
memory segment under OS/2. In this case the temporary screen buffer is created, 
accessed, and destroyed. Clearly, this technique can be used to manage memory 
within a given task. In the next section we consider the creation, access, and de- 
struction of a segment shared between two tasks. 
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3.2.2 Creating and Accessing a Shared Segment 


The program discussed in this section involves both a memory management function 
and multitasking. Although we do not formally address multitasking until Section 
3.3, it is useful to include it in this discussion because at least two processes are 
needed to demonstrate segment sharing. 

The program illustrated in Figure 3.4 opens with the following API call (which 
creates the shared segment): 


@DosAllocShrSeg shared_length,shrname,shrsel 


Here shared_length has been set at 404 bytes. These will correspond to 400 bytes (4 
extra bytes used to contain parameter data) that contain the corner values for boxes 
(xb, xe, yb, and ye). Further, these corner values will consist of numbers between 0 
and 200; hence the full height of the display screen will be used but only the first 
200 columns. 

The parameter shrname is a symbolic name to be associated with the shared 
memory segment to be allocated. The name string must include the prefix 


\SHAREMEM\... 
We choose 
‘\ SHAREMEM\SDAT.DAT’ ,o 


which is a zero-terminated string. Finally, shrsel is the shared segment selector. The 
name string for the shared segment must be common to all modules that use this 
segment and hence provides the link for ensuring that the same protected segment 
is accessed. 

In Figure 3.4, once the shared segment is allocated, the buffer contained in this 
segment is set to zero. Next a child process is executed using the statement 


@DosExecPgm obj name buf, lobj_name_buf, async, argptr, envptr, 
pid, prgm_nm 


where obj _name_buf is a buffer containing error pointers, lobj name_buf is the 
length of this buffer, async = 1 indicates the two processes execute asynchronously, 
argptr = O, envptr = O, pid contains return codes, and prgm_num is the name of the 
file to be executed (in this case NOS261.EXE, which is zero terminated). This 
causes the process in Figure 3.5 to execute, NOS261.ASM. 

The process NOS261.ASM gets the shared segment using 


@DosGetShrSeg shrname, shrsel 


where the shared name, shrname, is the same but a new selector is assigned. Next, 
a sequence of random numbers are loaded into the shared segment locations based 
on the following formula [3]: 


x, = (2053 x, + 13,849) mod 2" (3.1) 


106 


a 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 


PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 


dgroup 
STACK 


STACK 

’ 

DATA 
viohdl 
result 
action 
tr 

le 

br 

re 
no_line 
blank 
CGAm 
lmodeE 
typeCGA 
colCGA 
txtcCGA 
txtrCGA 
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TITLE 0S2512 - This is the calling OS/2 program (NOS2512.ASM) 


DESCRIPTION: This program plots boxes in protected 

mode and hesitates using a keyboard delay. Graphics 

mode 05H is used to display the boxes. It is the same 

as OS24 except it uses external modules. This routine 
employs multitasking to access the input box parameters, 
which are generated randomly (100 boxes in square 200 x 200). 
The program prints graphics under program control. 


boxx: FAR, cls: FAR,c1SCGA: FAR, scr_1d:FAR,prtscr: FAR 


viohdl,tr,lc,br,rc,no_line,blank,CGAm, lmodeE, typeCGA,colCGA 
txtcCGA, txtrCGA,hrCGA,vrCGA,STDm, lmode80, type8s0,col80 
txtc80,txtr80,hr8s0,vr8s0,waitf,dstat, PVBPtr1,bufstl1,buflenl,physell 
MASK1,MASK11,OFFSET1, four,xx,dummy, two, xxx,eighty,row,col 
address,x,y,xb,xe,ye,yb 


in_buffer,in_bufferl,in_buffer2,in_buffer3,in_buffer4 
bytesin, bytesinl,bytesin2,bytesin3,bytesout 
dev_name,dev_hand,dev_act,dev_size,dev_attr,dev_flag 
dev_mode,dev_rsv,MM,col1,N 

s,eight,eighty, four,shift1,scr_buffer 
sixforty,N4,ddd,w,bl 


include sysmac.inc 


-sall ;Suppresses macro lists 
GROUP data 


SEGMENT PARA STACK 'STACK'! 
db 256 dup('STACK ') 
ENDS 


SEGMENT PARA PUBLIC 'DATA' 


;Required video handle 
;Completion code 
;Terminates current thread 
;Top row screen clear 
;Left column screen clear 
;Bottom row screen clear 
;Right column screen clear 
;Number lines scrolled 
;Blank character pair 


;Video mode structure-CGA 
;Structure length 
00000111B ;Mode identifier 
2 ;Color option-Mode 5 
40 ;text characters/line-ignore 
25 ;text lines-ignore 


Figure 3.4 The program nos2512.asm, which creates a shared segment, creates 
a child process, and prints the screen. 
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hrCGA 320 

vrCGA 200 

STDm FAR 
lmodes0 12 

types0 00000001B 
cols0o 4 

txtcs80 80 

txtrso 25 

hrso 720 

vr8s0 400 


kbd_buf db 80 
lkbd_buf dw $-kbd_buf 
iowait dw ) 
kbdhdl equ fe) 


waitf equ 1 
dstat db z 


PVBPtrl1 label FAR 
bufstl dd OB8000H 
buflenl dd 8000H 
physell dw 


MASK1 ab 
MASK1i1 dw 
OFFSET1 dw 
four dw 
XX dw 
dummy dw 
two db 
XXX db 
eighty dw 
zero daw 
one dw 
row daw 
col dw 
address dw 


YVVVRP OO VN Ved > 


dw 
dw 
dw 
dw 
dw 
dw 


YQ eV ed VI oI ov) 


obj_name_buf 
lobj_name_buf 
async dw 
argptr dw 
envptr dw 
pid dw 
dw : 
prgm_nm db 


10 dup(0) 
$-obj_name_buf 


Poa 
=a 


-=<NvVvO O 


NOS261.EXE',0 


shared_length dw 404 
shrname db '\ SHAREMEM\SDAT.DAT',0 
shrsel dw 2 


400 dup(?) 
? 
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shorizontal resolution 
:vertical resolution 


Video mode structure-80x25 
;Structure length 

;Mode identifier-Mode 3+ 
;Color option 

;text characters/line 

;text lines 

shorizontal resolution 
;vertical resolution 


;Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
;Returned status 


;Video buffer structure 
;Start physical address 
;Buffer length 

;0S/2 screen buffer selector 


7;PEL byte mask 
;Odd/even row mask 
;Odd row buffer offset 


;PEL modulo parameter 
780287 dummy "pop" 


;Output value 


;row 
;column 
;Address screen dot 


;Box col parameter 
7;Box row parameter 
;Start column 

;End column 

;Start row 

7;End row 


;object name buffer 
;buffer length 

;Flag indicates async 
70 for argument ptr 

70 for environment ptr 
;Process ID result code 


;program name & parameter 
;Length shared buffer 
;selector 


;Buffer for shared data 
;Buffer size in bytes 


Figure 3.4 (Continued) 
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eight dw 
in_buffer 
in_bufferl 
in_buffer2 
in_buffer3 
in_buffer4 
bytesin 
bytesinl 
bytesin2 
bytesin3 
bytesout 

’ 

dev_name 
dev_hand 
dev_act 
dev_size 
dev_attr 
dev_flag 
dev_mode 
dev_rsv dd 
N4 dw 
MM 

W 

coll 

bl 

N 

shiftl 

s 

ddd 
sixforty 
scr_buffer 


SEGMENT PARA PUBLIC 


320 dup(0) 
1Bh,4BH, 64D, 01H 
ODH, OAH 

1BH, 41H, 08H 
1BH, 32H 

320 

4 


2 
3 
0 


00000001b 


0000000011000001b 


40H, 10H,04H,01H 

128 ,64,32,16,8,4,2¢1 
320 dup(?) 

4 dup(?) 

> 


640 
16384 dup(0) 


"CODE! 


assume cs:cseg,ds:dgroup 


PROC 


FAR 


sprint buffer 
;printer setup 
;LF/CR 


e 
’ 


;print buffer count 

;count bytes in_bufferl 
;count bytes in_buffer2 
;count bytes in_buffer3 


;name of printer device 
;device handle 
; 


e 
, 


;open file 


;pel mask 
;pin weights 
;columns 


;temporary buffer 


@DosAllocShrSeg shared_length,shrname,shrsel 


cmp 


ax,0 


jz NO_ERROR1 


jmp 


NO_ERROR1: 


! 


ERROR1 


push shrsel 


pop 


mov 
mov 


mov 
mov 


mov 
mov 
sub 
mov 


mov 
inc 


es 


ax,one 
es:[2],ax 


ax,Shared_length 
es:[0],ax 


di,four 
cx, shared_length 
cx, four 
ax, zero 


es:[di],al 
di 


loop lloop 


7Check on successful creation 
;Successful 
;Error 


e 
’ 


;Save selector 
;Selector in extra segment 


e 
’ 


;Flag indicating creation 

;Length shared buffer 

;Length parameter passed-multitask 
;Data record offset in buffer 
;Data buffer length + 4 

;Data buffer length 

;Clear character 


;Clear buffer 
;Next buffer point 


Figure 3.4 (Continued) 


;hdl private,deny none,w/o 
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@DosExecPgm obj _name_buf,lobj_name_buf,async,argptr,envptr,pid,prgm_nm 


cmp ax,0 
jz NO_ERROR2 
jmp ERROR2 


NO_ERROR2: 
; 


mov ax,zero 


NO_ERROR22: 


cmp es:[2],ax 
jz MEM_CL 
jmp NO_ERROR22 


mov si,zero 

mov di,four 

mov cx,shared_length 
sub cx, four 

mov count,cx 


mov al,es: [di] 
mov ESDI[si],al 
ine di 

inc si 

loop loop22 


call cls 

@VioSetMode CGAm,viohdl 

call clsCGA 

@VioScrLock waitf,dstat,viohdl 
@vioGetPhysBuf PVBPtr1,viohdl 
push physell 

pop es 


mov di,O 

mov dax,0 

mov ax,count 
div four 

MOv cCx,ax 


push cx 

mov al,ESDI[di] 

mov ah,ESDI[di+1] 

cmp ah,al 

jne EELSE1 
mov al,170 
mov ah,180 
call xload 
jmp IIF1 


cmp ah,al 

jle ELSE1 
call xload 
jmp IIF1 


mov bl,al 
mov al,ah 
mov ah,bl 
call xload 


al, ESDI[di+2] 
ah, ESDI[di+3] 
ah,al 
EELSE2 


;Check error condition 
;Jump no error 
;Jump error 


;Indicates buffer write complete 


Check buffer write 
;Jump if buffer write complete 
;Otherwise wait 


;Offset in intermediate buffer 
;Offset in shared buffer 
;Length data buffer + 4 
;Length data buffer 

;Data buffer size in bytes 


;Obtain shared buffer value 

;Load shared memory buffer 
;Increment shared buffer ptr 
;Increment intermediate buffer ptr 


;Clear screen 

;Set CGA graphics mode 

;Clear CGA screen 

;Lock screen context 

;Get physical buffer selector 
;Save selector 

;Load selector into extra segment 


;Intermediate buffer offset 
;Clear upper dividand 

;Data buffer byte count 
;Reduce to sets of four 
;Loop count 


;Save loop count 

;Obtain 1st buffer value-set 
;Obtain 2nd buffer value-set 
;Check values equal 

;Arbitrarily set lst equal value 
;Arbitrarily set 2nd equal value 
;Load xb and xe 

;Check ah g.t. al 


;Load xb and xe 


;Swap ah and al 


;Load xb and xe 


;Obtain 3rd buffer value-set 
;Obtain 4th buffer value-set 
;Check values equal 


Figure 3.4 (Continued) 
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cmp 
jle 


mov al,170 
mov ah,180 
call yload 
jmp IIF2 


ah,al 
ELSE2 
call yload 
jmp IIF2 


mov bl,al 


mov al,ah 
mov ah,bl 


call yload 


push di 


cal 


pop 
add 


pop 


1 boxx 
di 
di,four 


cx 


loop loop2 


cal 


@vi 


1 scr_ld 


oScrUnLock 


viohdl 


;Arbitrarily set 1st equal value 
;Arbitrarily set 2nd equal value 
;Load yb and ye 

;Check ah g.t. al 


;Load yb and ye 


;Swap ah and al 


;Load yb and ye 

;Save buffer offset 

;Draw box 

;Recall buffer offset 
;Increment data ptr 4 bytes 


;Recall loop count 


;load screen print buffers 


;Unlock screen context 


@KbdStringIn kbd_buf,1lkbd_buf, iowait, kbdhdl ;hesitate 
@VioSetMode STDm,viohdl 


@DosKillProcess 1,pid 


@DosFreeSeg shrsel 


cal 


1 prtscr 


@DosClose dev_hand 
@DosExit action,result 


END 


PRO 
mov 
mov 
mov 
mov 
mov 
mov 
ret 
END 


PRO 
mov 
mMOv 
Mov 
Mov 
mov 
mov 
ret 
END 


END 
END 


P 


Cc NEAR 
bh,0 
bl,al 
xb, bx 
bh, 0 
bl,ah 
xe, bx 


P 


Cc NEAR 
bh,0 
bl,al 
yb,bx 
bh, 0 
bl,ah 
ye, bx 


P 


S) 


Figure 3.4 


780 x 25 alpha mode 
;Terminate child process 


;Free shared memory 


;Terminate process 


;Clear upper register half 
;al = start 

;Load xb less than 199 
;Clear upper register half 
;ah = end 

;Load xe less than 199 


;Clear upper register half 
zal = start 

;Load yb less than 199 
;Clear upper register half 
;ah = end 

;Load ye less than 199 


(Concluded) 
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TITLE O0S261 - Generates multitask r.n. 


Fi we © se Se Se Ne 
hy fo) 
hk oO 

oo 

“I 


ENDIF 


; 
dgroup 
STACK1 
STACK1 
DATA1 


tA 
rndl1 

? 
one 
action 
result 
ssize 
shrsel 
shrname 
zero 


’ 
DATA1 


CSEG1 


0S261 


’ 


Figure 3.5 The child process nos261.asm, used to generate random numbers in 
a Protected Mode multitasked environment. 
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(0S261.ASM) 


DESCRIPTION: This process generates the multitasked 


random numbers. 


include sysmac.inc 


-sall 
GROUP datal 

SEGMENT PARA STACK 'STACK! 
db 256 dup('STACK1 ') 
ENDS 


SEGMENT PARA PUBLIC 'DATA'! 
dw 


dw 
equ 
dw 
dw 
dw 


dw 
ENDS 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:csegl1,ds:dgroup 
PROC FAR 


mov ax,one 
mov rndl,ax 
@DosGetShrSeg shrname,shrsel 
push shrsel 


pop es 


mov ax,es:[0] 
mov ssize,ax 


mov di,4 
mov cx,ssize 
sub cx,4 


mov al,0O 

mov es:[di],al 
inc di 

loop loopl 


mov di,4 
mov cx,ssize 


sub cx,4 


call ldmem 
mov es:[di],al 
inc di 

loop loop2 


db \SHAREMEM\SDAT. DAT! , 0 


It is called by the plot process. 


;Suppresses macro lists 


;seed value 


;Buffer size + 4 
7;Selector 
;Shared memory name 


;Load initial seed value 


;Get shared segment 
;Save selector 
;Selector to extra segment 


;Establish shared buffer size 
;Define buffer size + 4 


;Pointer to data buffer 
;Loop byte count + 4 
;Loop byte count 


;Clear buffer 
;Buffer write 
;Increment offset 


;Pointer to data buffer 
;Loop byte count + 4 


;Loop byte count 


;Generate random value 
;Load shared buffer (byte) 
;Increment byte offset 
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mov ax, zero ;Flag indicating write complete 
mov es:[2],ax ;Flag loaded 


’ 


@DosFreeSeg shrsel 
@DosExit action, result 


ENDP 


PROC NEAR 


;Generate r.n. 
mov dax,0 ;Load upper multiplicand zero 
mov ax,rndl ;Load previous r.n. 
mov bx,2053 ;Multiplier 


mul bx 
mov bx,13849 ;Load additative constant 


ax, bx ;Add low order result 
ax,0 ;Add carry if needed 
bx, OFFFFH ;Load 2(16) - 1 
;Calculate modulo 
;Move remainder into ax 
;Save r.n. 
;Scale r.n. to less than 200 
;Clear upper dividand 
;Scale 
;Save al 


0S261 


Figure 3.5 (Concluded) 


Here x ,, is the (n + 1)th number and x, the nth number(s). The procedure ldmem 
contains the code that calculates this random sequence. Once the sequence is calcu- 
lated, the size of the buffer is checked. This size was loaded as a word at es:[0] in 
the creating routine. In NOS261.ASM the value is used to set the number of random 
values to be calculated (here this is 400). 

Next, NOS261.ASM frees the shared segment using 


@DosFreeSeg shrsel 


and exits back to OS/2. Prior to freeing the segment, however, NOS261.ASM loads 
a zero at es:[2] to indicate that the buffer write is complete. (This value was previ- 
ously set to 1.) The main calling program, NOS2512.ASM, sits in a loop checking 
es:[2] for a value of zero. (This is a somewhat wasteful operation and could be used 
asynchronously to accomplish other tasks if needed.) Once the random values have 
been completely loaded and NOS2512.ASM becomes aware of this, it terminates the 
loop and reloads these shared values into a buffer, ESDI. The processing then 
continues in the usual fashion to clear the screen, set the CGA mode, and capture 
the physical screen buffer. Using two routines, xload and yload, the box corners are 
loaded, ensuring that (xb, yb) are always less than (xe, ye), respectively. The rou- 
tine boxx is called and the random boxes generated on the display. Figure 3.6 illus- 
trates the variant of boxx used for this call. Note that it includes a check on the 
corners to ensure that xb < xe and yb < ye. 
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TITLE 0S252 - Supplemental routines for box plotting (0S252.ASM) 


=e Se Se Se Ne Ot 


EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 


CSEG 
PUBLIC 


boxx 


; 
; 
; 
ELSE10: 


ELSE11: 


Figure 3.6 Supplemental routines necded by the random box generating 


DESCRIPTION: These routines set up box plots in CGA 
mode and hesitate using a keyboard delay. Graphics 
mode 05H is used to display the box. This set of routines 
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is called by box plotting main routine. 


include sysma 


-sall 


c.inc 


;Suppresses macro lists 


viohd1:WORD,tr:WORD,1c:WORD,br:WORD,rc:WORD 


no_line:WORD,blank: WORD, CGAm: FAR, 1modeE: WORD, typeCGA: BYTE 
CcolCGA: BYTE, txtcCGA:WORD, txtrCGA: WORD, hrCGA: WORD, vrCGA: WORD 
STDm: FAR, 1mode80:WORD, type80: BYTE, col80: BYTE, txtc80:WORD, txtr8s0:WORD 


hr80:WORD,vr8g 


waitf:WORD,dstat: BYTE, PVBPtr1: FAR, bufst1: DWORD 

buflenl1: DWORD, physel1:WORD,MASK1: BYTE, MASK11: WORD, OFFSET1: WORD 
four:WORD, xx:WORD, dummy: WORD, two: BYTE, xxx: BYTE, eighty: WORD 
row:WORD,col:WORD, address:WORD,x:WORD, y: WORD, xb: WORD, xe: WORD 


0: WORD 


yb: WORD, ye: WORD 


SEGMENT PARA 


PUBLIC 'CODE' 


cls,boxx,c1lsCGA 
assume cs:cseg 


PROC FAR 


xb = x-begin,xe = x-end,yb = y-begin,ye = y-end 


mov ax,xb 

cmp ax,xe 

j1 ELSE10 
xchg ax,xe 
mov xb,ax 


mov ax,yb 

cmp ax,ye 

jl ELSE11 
xchg ax,ye 
mov yb,ax 


mov ax,yb 
mov y,ax 
call lineh 
mov ax,ye 
mov y,ax 
call lineh 
mov ax,xb 
mov x,ax 
call linev 
mov ax,xe 
mov x,ax 
call linev 


ret 
ENDP 


PROC FAR 


;Check xb 1.t. 


;Swap xb and xe 


;Check yb 1.t. 


;Swap yb and ye 


;Top box line 


;Draw top horizontal line 


xe 


ye 


;Bottom box line 


;Draw bottom horizontal line 


;Left box line 


;Draw left vertical line 
;Right box line 


;Draw right vertical line 


@VioScrollUp tr,lc,br,rc,no_line,blank,viohdl 


routine, nos2512.asm. 
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ret 
; 
cls 
C1sCGA 


e 
’ 


ENDP 


PROC FAR 


@VioScrLock waitf,dstat,viohdl ;Lock screen context 


@VioGetPhysBuf PVBPtri1,viohdl ;Get physical buffer 
push physell ;Screen selector 
pop es ;Load extra segment 


mov bp,0O ;Start offset zero 
mov al,0 ;Zero attribute-clear 


mov es:[bp],al ;Clear byte 
inc bp 
cmp bp,1F3FH ;Check end 1st buffer 


jJle DO1 


mov bp, 2000H ;Offset 2nd buffer-odd 
mov al,0O ;Zero attribute-clear 


mov es:([bp],al 
inc bp 
cmp bp,3F3FH ;Check end 2nd buffer 
jle DO2 


;Clear byte 


@VioScrUnLock viohdl Unlock screen context 


° 
' 


ret 
clsCGA ENDP 


’ 
wdot PROC NEAR 


(col,row) = (x,y) 


fild four ;Load stack with 


fild col ?ST = col, ST(i) = 4 
fprem ;Modulo 
fistp xx ;Store remainder in xx 
fistp dummy ;Pop stack 
mov al,3 
mov bl,byte ptr xx 
sub al,bl 7(3 - col % 4) 
mov ah,0O ;Clear upper multiplicand 
mul two 
mov cl,al ;Shift value for PEL 
mov al,MASK1 ;PEL color mask 
shl al,cl ;Shift to correct PEL 
mov xXxx,al ;Store buffer value 
mov ax,row ;Begin address calculation 
shr ax,1 ;Divide row by 2 
mov dax,0 ;Clear upper multiplicand 
mul eighty 
mov bx,col ;Convert column value to bytes 
shr bx,1 
shr bx,1 
add ax,bx ;offset in ax 
mov address,ax ;Save offset base 
mov ax,row ;Check even/odd row 
and ax,MASK11 ;Look for bit 0 set 
cmp ax,0 
jle ELSE1 

mov ax,address 

add ax,OFFSET1 ;add odd buffer offset 


jmp IF11 
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mov ax,address 


mov bp,ax 
mov al,xXxx 


or es:[bp],al 


ret 
ENDP 


PROC NEAR 


y = row position, xb = begin, xe 


mov ax,y 
mov row,ax 


mov ax,xb 


mov col,ax 
push ax 
call wdot 
pop ax 

inc ax 

cmp ax,xe 
jle DO10 


ret 
ENDP 


PROC NEAR 


x = col position, yb = begin, ye 


mov ax,xX 
mov col,ax 


mov ax,yb 


mov row,ax 
push ax 
call wdot 
pop ax 

inc ax 

cmp ax,ye 
jle DO20 


ret 
ENDP 


ENDS 
END 


s;screen buffer address 
;Attribute value for dot 


Write dot 


= end 


s;Establish row for wdot 


;Establish start column 


;Save column value 

;Write dot (col,row) 
;Recall column 

;Increment column 

;Check end horizontal line 


e 
’ 


= end 


;Establish column for wdot 


:;Establish start row 


7;Save row value 

;Write dot (col,row) 
;Recall row 

;Increment row 

;Check end vertical line 


e 
’ 
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Figure 3.6 (Concluded) 


Once the boxes are plotted the keyboard hesitate takes place, followed by a 
call to prtscr that prints the screen content. A similar version of this program appears 
in reference 4, without the screen print logic. Figure 3.7 illustrates the plotted boxes. 


3.2.3 Changing Segment Size 


Among the API memory management services are functions for changing the size of 
an allocated segment. It is a prerequisite, however, that the segment be allocated 
during the existing session. Figure 3.8 presents a program that allocates and then 
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Figure 3.7 Screen print of the 100 
random boxes output by nos2512.asm. 


modifies the size of a segment. This program is somewhat artificial in that it serves 
no useful purpose other than to demonstrate this memory management technique. 
The program opens with the call 


@DosAllocSeg msize, msell, mflag 


Here msize is the desired size of the segment (in this case 4000H), in msel1 the 
returned selector, and mflag determines the type of segment access. Specifically, bits 
0 and 1, when set, permit sharing of the segment using DosGiveSeg and DosGetSeg, 
respectively. Bit 3 allows the segment to be discarded in low-memory situations. If 
the segments are shared, they can only be increased in size. We have set all three 
of these bits to 0. 

The next block of code pushes the allocated segment selector on the stack and 
pops it into es. Hence, es now points to the created segment. This segment is loaded 
with 2048 copies of the string “MEMORY ”, where two blank spaces have been 
added to the end of the string. Once completed, the call 


@DosReallocSeg msizel, msell 


is made and the segment size reduced to one byte beyond a paragraph boundary. At 
this point some mechanism must exist to check the segment definition. Subsequent 
code writes a 1 into the first location of the segment, followed by a write to the 
eighteenth position. The latter position should yield a protection violation. 

Figure 3.9 illustrates CodeView results for the program following creation of 
the memory segment. Note that beginning at address es:0x0000 (here 0x0000 speci- 
fies a hexadecimal address, 0000, in C notation), the string “MEMORY ” is loaded. 
A check at 0x4000 shows that the preceding 4000H locations are filled with this 
string also (Figure 3.9b). 
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TITLE MEMSEG -- Reallocate memory segment (memseg.asm) 


e 
’ 
e 
’ 
e 
’ 
° 
’ 
e 
’ 
° 
’ 


dgroup 


STACK 


STACK 
; 
DATA 


msize 
msell 
mflag 
blk_ct 
mem_wd 
msizel 
DATA 


’ 
CSEG 


OS21 


DESCRIPTION: This simple routine creates and reallocates 
a memory segment. The final memory instruction is 
designed to create a protection violation. The program 
should be run with CodeView. 


include sysmac.inc 


-sall 
GROUP data 


SEGMENT PARA STACK 'STACK'! 
db 256 dup ('STACK ‘') 
ENDS 


SEGMENT PARA PUBLIC 'DATA' 


dw 16385 ;buffer size 

dw ? ;selector 

dw OO0O00000000000000B ;not sharable 
dw 16384 block count 

ab 'M','E','M','O!', 7 ! YS ' ;string 
dw LT ;new buffer size 


ENDS 


SEGMENT PARA PUBLIC 'CODE' 
assume cs:cseg,ds:dgroup 
PROC FAR 


@DosAllocSeg msize,mselil,mflag ;allocate segment 


push msell 
pop es 


mov dx,blk_ct sblock counter limit 
mov di,O ;buffer block count 
lea bp,mem_wd ;string address 


mov cx,8 ;count limit for string 
mov si,O ;index for string/buffer 


mov al,ds: [bp+si] ;load from string 
mov es:[dij],al ;load buffer 

inc si ;increment string 

inc di ;increment block byte 
loop LOOP2 


cmp di,dx ;check block limit 
j1 LOOP1 


@DosReallocSeg msizel,msell ;reallocate segment 


push msell ;preserve selector 

pop es ;create extra segment 

mov bp,0O ;segment index 

mov al,l load dummy value 

mov es: [bp],al ;Single load in buffer 
mov es: [bp+17]),al ;PROTECTION VIOLATION 


Figure 3.8 Simple routine for creating and reallocating memory. 
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@DosExit 1,0 


’ 

0S21 ENDP 

CSEG ENDS 
END 


Figure 3.8 (Concluded) 


File Search View Run Watch Options Calls Trace! Go! MEMSEG. EXE 
iecteaiaite Sa 


OO3F:002F 268805 MOV Byte Ptr ES: [DIJ],AL 
O03F:0032 46 

O03F:0033 47 

OO03F:0034 E2F6 

OO3F:0036 3BFA 

O003F:0038 T7CEC 

O003F:003A A11000 AX, Word Ptr [001 


re perry caren | 


IBM CodeView (R) Version 1.00 

Copyright (C) IBM Corporation 1987 

Copyright (C) Microsoft (R) Corporation 1986, 1987 
>d es:0x0000 

OO6F:0000 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
OO6F:0010 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
OO6F:0020 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
OO6F:0030 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
OO6F:0040 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
OO6F:0050 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
OO6F:0060 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
OO6F:0070 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 
> 


(a) 


Figure 3.9 Facsimile CodeView output, illustrating (a) low end of initialized memory 
segment and (b) high end of initialized memory segment. (Courtesy of the Microsoft 
Corporation.) 
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le Search View Run Watch Options Calls Trace! Go! MEMSEG. EXE 


sseaernnetontionmsi tern ocean [orreia rere iierstietcshrrmsitenieienSnsuiiretimtiesy A 


003F: 
OO3F: 
OOSH's 
OOSF: 
003F: 
003F: 
003F: 


003F 


OO6F 
OO6F 


>»d es:0x3ff0 


OO6F 
OO6F 
OO6F 
OO6F 
OO6F 
OO6F 
OO6F 
OO6F 
> 


002C 3E8A02 MOV AL, Byte Ptx DS: (BP+S1 } 
OO2F 268805 MOV Byte Ptr ES: [DI], AL 
0032 46 INC SI 

0033 47 DI 

0034 EH2F6 002C 

0036 3BFA DI, DX 

0038 CEC 0026 

:003A A11000 AX,Word Ptr [0010] 


:0060 4D 45 MEMORY MEMORY 
:0070 4D 45 MEMORY MEMORY 


: 3FFO 45 MEMORY MEMORY 
54000 72 72 22 27 8? 72 7? Vee? VT T2 Ve Te ee Vl PR PRET eee ee re ee 
°4010 2% 2% 

-4020 ?? 2° 

-4030 7? ?? 

-4040 ?? ?° 

:4050 ?? ?? 

>4060 ?? ?? 


(b) 
Figure 3.9 (Concluded) 


Figure 3.10a corresponds to execution up to 0O3F:0055, in which the resized 
segment now has its first location loaded with 1. Figure 3.10b corresponds to exe- 
cution of 003F:0055 and the subsequent violation is noted. 

Figure 3.11 illustrates CodeView output for the case when a segment violation 
might occur except that the segment is defined as sharable with bits O and 1 of 
mflag set. In this case the attempt to reallocate the size of the segment downward 
to 17 bytes fails and the initial segment size remains implemented. The instruction 
O03F:0055 executes as the segment data indicate. 


3.2.4 Creating and Accessing Huge Segments 


The OS/2 kernel (level 0) allocates and maintains segment descriptors. This provides 
a mapping of the virtual address space onto the physical memory space. OS/2 does, 
in fact, allow the user the capability to request and use more memory than exists in 
his or her system. This is accomplished using extended file management techniques. 
A very key boundary under DOS and within the confines of the Intel 8086 family 
of architectures is the 64K boundary or segment size. OS/2 has API services that 
allow the user to extend a huge memory block because the underlying segments are 
still in place. The system simply provides additional selectors, as needed, to access 
the subsequent high-memory spaces. 
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File Search View Run Watch Options Calls Trace! Go! MEMSEG. EXE 


>0042 9A0000B345 CALL 45B3:0000 

:0047 FF360200 PUSH Word Ptr [0002] 

:004B 07 

:004C BDOOOO 

:004F BOOL AL,O1 

:0051 26884600 Byte Ptr ES: [BP+00], AL 


OO3F:0055 26884611 MOV Byte Ptr ES: [BP+11], AL 
OO3F:0059 B80100 MOV AX, 0001 


| 


Copyright (C) IBM Corporation 1987 
Copyright (C) Microsoft (R) Corporation 1986, 1987 
>d es:0x0000 
Q1 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 .EMORY MEMORY 
sca ee at cae di a at a Si a! en dh ek a ee a a a a a ae a ee ae a a ke a 
To VE OS SET OP 2? 22H 7T? 92 8? Pe 2 
a cee + a ae Gee a ee a ee a ee os a ee 
22 8? 22 22 22 27 22 22=27 2? 77 V2 2? 
22? 22 22 2? OF OF 2? VAT? 22 22 2? Pe 
C2 97 2? 2C Eo VE PT P9788 er? 2 2. V2 
eo TC VP Ie FF Te Re Ht t Te TT eT. ee 


BSN SSAA Qa SESS Sa SO 


Search View Run Watch Options Calls Trace! Go! MEMSEG. EXE 
Annan ERE 

9A0000B345 45B3:0000 
FF360200 Word Ptr [0002] 


AL,O1 
26884600 Byte Ptr ES: [BP+00],AL 
26884611 Byte Ptr ES: [BP+11],AL 
B80100 AX, 0001 


sanaeesseamaeeamnenaeraemmmnncemesiauanastaumecancecwecameeaeectaianiaaeeanamamaianemnmanammaaenaaan 


Copyright (C) Microsoft (R) Corporation 1986, 1987 
>d es:0x0000 

OO6F:0000 O1 45 4D 4F 52 20-4D 45 4D 4F 52 .EMORY MEMORY 
OO6F:0010 77 29 77 22 79 OF 2? P2=77 229 72 2? 2? 
OO6F:0020 77 2? 99 22 22 22 22 B2=—?2 22 7 3? 2? 
HOGF:00380 ?7 27 22 7? 2? FT? 22 @2-2? 27 77 2% Fe 
OO6F:0040 977 27 27 272 22 22 PP 22-2997 7? 2? 2? 22 
OUBHF:0050 77 9? 2 2? Ve PE PP S2=-2F 2 Be 27 F2 
OOBF:0060 7? 27 7? 82 277 272 7? F2=?T Be 2? 2 Te 
OO6F:0070 72 292 277 2? 299 2? 8? 89-79 TV? 22 7? 29 
>Segmentation violation 


(b) 


Figure 3.10 Facilimile CodeView output, illustrating (a) reallocated memory and (b) 
reallocated memory with protection violation. (Courtesy of the Microsoft Corporation.) 
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File Search View Run Watch Options Calls Trace! Go! MEMSEG. EXE 


OO3F: 
003F: 
O03F: 
OOSF: 
OOSrs 
OO03F: 
OO3F: 


003F 


O7E7 
O7E7 


> 


:0060 4D 45 20-4D 45 4D 
:0070 4D 45 20-4D 45 4D 
>d es:0x0000 

O7ET: 
O7E7: 
UTET: 
O7E7: 
O7E7: 
OTE: 
OTET: 
OTET * 


Soe ey. pe nr ee a ee 


0042 9A0000B345 CALL 45B3:0000 

0047 FF360200 PUSH Word Ptr [0002] 

004B 07 POP ES 

004C BDOOOO MOV BP, 0000 

OO4F BOOL MOV AL,O1 

0051 26884600 MOV Byte Ptr ES: [BP+00], AL 
0055 26884611 Byte Ptr ES: [BP+11], AL 


:0059 B80100 AX, 0001 


0000 O1 45 20-4D 45 
0010 4D O1 20-4D 45 
0020 4D 45 20-4D 45 
0030 4D 45 20-4D 45 
0040 4D 45 20-4D 45 
0050 4D 45 20-4D 45 
0060 4D 45 20-4D 45 
OO7O0 4D 45 20-4D 45 


Figure 3.11 Facsimile CodeView output, illustrating reallocated memory for the conditions 
of Figure 3.10b with sharable memory. Note: There is no protection violation. (Courtesy 
of the Microsoft Corporation.) 


Figure 3.12 illustrates a program hugeseg.asm, which is used for allocating 
such a huge segment. In this case 81,920 bytes are allocated. The initial call is 


@DosAllocHuge mnumseg, msize, msell, msegmax, mflag 


where 
mnumseg number of 64K whole blocks in segment 
msize number of bytes in last non-whole block 
msell selector 
msegmax maximum number of 64K whole segments occupied 


(set = O means the segment can only be decreased) 


mflag bit O=1 (shareable through DosGiveSeg) 
bit 1=1 (shareable through DosGetSeg) 


bit 2=1 (discardable in low-memory cases) 


In the program we use one 64K whole segment and a partial memory block of 
16,384 bytes. The initial selector value returned by @DosAllocHuge points to the 
first block in the huge segment. Subsequent blocks must be accessed using 
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TITLE HUGESEG -- Allocate a huge segment (hugeseg.asm) 


DESCRIPTION: This program allocates a huge segment: 


2 (65536) and 1 (16384) byte 64k blocks. 


using CodeView. 


include sysmac.inc 
ENDIF 
? 

-sall 


dgroup GROUP data 


t 
STACK SEGMENT PARA STACK 'STACK'! 
db 256 dup ('STACK ‘) 
STACK ENDS 
DATA 
mnumseg dw 

msize dw 

msell dw 

msegmax dw 

mflag dw 0000000000000111B 
blk_ct dw 8192,2048 
shift_ct dw 2 
mem_wd db , EM", 70° , 
mseg_ct dw 

two dw 


SEGMENT PARA PUBLIC 'DATA' 


DATA ENDS 


CSEG SEGMENT PARA PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup 
0S21 PROC FAR 

@DosAllocHuge 


mov si,0O 
push si 


pop si 

mov ax,msell 
cmp si,1 

j1 ELSE1 


@DosGetHugeShift 
mov bx,1 

mov cl,byte ptr shift_ct 
shl bx,cl 

mov ax,msell 

add ax,bx 


shift ict 


mov msell,ax 


push si 

mov ax,Si 

mul two 

mov si,ax 

mov dx,blk_ct[si] 
pop si 


Figure 3.12 
(81,920 bytes). 


'R!, ry 


It is checked 


;suppresses listing 


snumber 64k whole blocks 
;bytes in last block (partial) 
7;selector 

;maximum realloc 64k blocks 
;segment characteristics 
;bytes in each block 

;shift count 

' ' ' 1 


v 
sblock counter (0,1) 


mnumseg,msize,msell,msegmax,mflag 


;block index 
;preserve index 


;recall block index 
;load selector 

;check if 1st block 
rjump if ist block 


;get shift count 

s;bx to be shifted 
;load shift as byte 
;amount shifted 
;reload selector 
;create new selector 


s;reload selector 


;block byte sount 


The program hugescg.asm, used for allocating a huge segment 


Chap. 3 


Memory Management Activities 


mov di,O 

lea bp,mem_wd 
inc si 

push si 

push msell 


123 


sblock internal index 
s;address "MEMORY " 
s;increment block count 
;preserve block count 
7;selector 


;selector in es 
sload block string count 


;string index 


al,ds: [bpt+si] 
es: [di],al 


;load string member 

;insert in huge segment 
;increase string index 
;increase huge segment index 
;check string count 


loop LOOP1 


srecall block count 
slast block? 
;preserve block count 


pop si 

cmp si,mseg_ct 
push si 

jle LOOP3 


@DosFreeSeg msell 
@DosExit 1,0 
ENDP 


ENDS 
END 


Figure 3.12 (Concluded) 


@DosGetHugeShift. This provides a shift count that can be used to calculate an off- 
set. Note that the call 


@DosGetHugeShift shift_ct 


returns a shift count in shift_ct. The selector offset increment is obtained by shift- 
ing the value 1 to the left by the amount specified as the shift count, shift_ct. This 
is then added to the selector value to get the new selector. For example, suppose 
that the selector is 6F7H. If the shift count returned is 4, an increment of 16 must 
be added to 6F7H to get the new selector: 707H. If several blocks have been allo- 
cated, the selector for each must be obtained by adding the increment to each suc- 
cessive selector to obtain the following value. 

In Figure 3.12 a check is made on whether the first block is being processed 
(si less than 1) and the shift count processing implemented as needed. The word 
“MEMORY ” is then written into the memory block. Finally, the block is released 
using @DosFreeSeg. Figure 3.13 illustrates the CodeView memory dump Starting at 
0O7F7:FFFO, the end of the segment. Since the listing wraps around at 07F7:FFFF, it 
is clear that the 64K block is filled with “MEMORY ”. Figure 3.14a illustrates the 
beginning of the last partial segment and Figure 3.14b the end of this partial seg- 
ment (16,384 bytes long). The partial segment is, of course, also loaded with 
“MEMORY ”, indicating that the allocation and use of the huge segment (81,920 
bytes) was successful. 
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File Search View Run Watch Options Calls Trace! Go! HUGESEG. EXE 


0OO03F:0068 BEOOOD MOV SI,0000 

OO03F:006B 3E8A02 MOV AL,Byte Ptr DS: [BP+STI] 
OO3F:006E 268805 MOV Byte Ptr ES: [DI],AL 
OO3F:0071 46 INC SI 

OO3F:0072 A7 INC DI 

O0O03F:0073 83FE07 CMP SI,+07 

OO03F:0076 T7EF3 JLE OO6B 

0OO03F:0078 E2EE LOOP 0068 e 
OO3F:007A 5E POP SI 

i 
O7F7:0070 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 59 20 20 
>d es:O0xfff0 

O7F7:FFFO 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 59 20 20 
O7F7:0000 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 59 20 20 
O7F7:0010 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 59 20 20 
O7F7:0020 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 59 20 20 
O7F7:0030 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 59 20 20 
O7F7:0040 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 59 20 20 
O7F7:0050 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 59 20 20 
O7F7:0060 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 52 59 20 20 
> 


Figure 3.13 Facsimile CodeView output, illustrating loading through first 64K block limits 
(07F7:0000 through 07F7:FFFF) of huge segment. (Courtesy of the Microsoft Corporation.) 


= File Search View Run Watch Options 


Oe aaeeenens bmn Mattern arto T oseneenekacaeanlecnentaliglacislarealontararlantavenlor tat lanhelheinlenleateltestelarenttalent 


OO3F:006E 268805 MOV Byte Ptr ES: [DI],AL 
OO3F:0071 46 INC ol 

OO3F:0072 47 INC DI 

O03F:0073 83FE07 CMP SI,+07 

OO3F:0076 7EF3 JLE OO6B 

Q03F:0078 E2EER LOOP 0068 

OO3F: 007A FUP ol 

003F:007B 3B361800 CMP SI,Word Ptr [0018] 


one pewenee tees 


Copyright (C) IBM Corporation 1987 

Copyright (C) Microsoft (R) Corporation 1986, 1987 
>d es:0x0000 

0807:0000 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 
0807:0010 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 
0807:0020 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 
0807:0030 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 
0807:0040 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 
0807:0050 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 
0807:0060 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 
0807:0070 4D 45 4D 4F 52 59 20 20-4D 45 4D 4F 
i 


Figure 3.14a Facsimile CodeView output, illustrating (a) loading of second block start 
(0807:0000) and (b) loading through second block end (0807:3FFF) of huge segment. 
(Courtesy of the Microsoft Corporation.) 
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= File Search View Run Watch Options Calls Trace! Go! HUGESEG. EXE 
Sis aaa ee 
OO3F:007B 3B361800 CMP SI,Word Ptr [0018] 


pd 
003F:007F PUSH SI 2 
003F:0080 JLE 0022 


OO03F:0082 MOV AX,Word Ptr [0004] 
PUSH AX 
9AO000BB45 CALL 45BB:0000 
B80100 MOV AX, 0001 
50 PUSH AX 
B80000 MOV AX, 0000 


0807:0070 4D 59 20-4D 45 4D MEMORY MEMORY 
>d es:0x3ff0 

O0807:3FFO 4D 59 20-4D 45 4D MEMORY MEMORY 
OB07:4000 77 79 22 22 2? 29 22 22=277 22 27 FF PF OP OF Be PPPOE 22 e ee TT eT? 
U807:4010 77 7? 27 27¢ 22 2? 22 292-27 T? 27 

US07Ts4020 7 7? 22 2? 2 7? V2 22-7? 22 ez 

O807: 4080 92? 27 29 27 72 82 72 V2=-77 Pe FF? 

O807: 4040 7? 7? 27 29 9? 22 27 29=77 ?? 2? 

O807: 4050 77 7? 22 82 2? 22 22 FU-7? 7? 2? 

OBOT?4000 ?? Te 2 Fe 20 C2 22 FeH=27% CP 2? 

> 


Figure 3.14b (Concluded) 


OS/2 could have been structured to provide automatic memory management 
features, but this would have removed some of the flexibility of the operating sys- 
tem. The ability to clean up memory and segregate usage expands the programmer’s 
access to more difficult problem-solving techniques. This is somewhat philosophi- 
cal and the actual implementation of memory allocation is left up to the individual 
user. It is, of course, essential for programs that push the limits of the physical 
system resources. 


3.2.5 Suballocating Memory 


The final memory management activity considered in this section is suballocation. 
This is the blocking of memory within an allocated segment and is best used if an 
application requests and frees small portions of memory at a frequent rate. It has the 
advantage that an allocation at the physical level is not needed. When a normal 
allocation occurs an LDT entry must be defined, a descriptor defined, physical 
memory located, and then the reverse when memory is released. The memory sub- 
allocation package (MSP) contains the calls 


@DosSubAlloc 
@DosSubSet 
@DosSubFree 


which allow the allocation and freeing of portions of a segment without incurring 
the system overhead. The services in the MSP simply keep track of which portions 
of the memory segment are in use. 
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Figure 3.15 presents a program that implements a memory suballocation 
operation. Basically, a segment with 16,385 bytes is allocated using @DosAllocSeg. 
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TITLE SUBALLO -- Reallocate memory segment (suballo.asm) 


FH we we we Ne 


Fl 


ENDIF 


dgroup 
STACK 
STACK 
DATA 

; 
msize 
msell 
mflag 
blk_ct 
mem_wd 
msizel 


moffset 
two 


’ 
DATA 
; 
CSEG 


OS21 


=e 


=e 


LOOP4: 


=e 


LOOP1: 


LOOP2: 


DESCRIPTION: This simple routine creates and suballocates 


a memory segment. 


include sysmac.inc 


-sall 

GROUP data 

SEGMENT PARA STACK 'STACK'! 
db 256 dup ('STACK ) 
ENDS 

SEGMENT PARA PUBLIC 'DATA!' 
daw 16385 

aw ? 

dw OOO0OO0000000000000B 
dw 16384,8192 

ab 'M',"E','M','O','R!','y!, 
dw 8192 

aw 0 

dw 2 

ENDS 

SEGMENT PARA PUBLIC 'CODE'! 


assume cs:cseg,ds:dgroup 
PROC FAR 


@DosAllocSeg 


push msell 
pop es 


mov di,O 
mov si,0O 
push si 
push di 


di 
si 


pop 
pop 
mov dadx,blk_ct[si] 
lea bp,mem_wd[di] 
mov di,moffset 
push si 

push di 


mov 
mov 


si,0O 


al,ds: [bp+si] 
es:[dij],al 


mov 
mov 
inc si 
ane ai 
loop LOOP2 


push di 
sub di,moffset 


msize,msell1,mflag 


The program should be run with CodeView. 


s;buffer size 

;selector 

snot sharable 

block count 

' ‘8 's' yt, 'Bt, At, Lh", 
;suballocated size | 
;offset to suballocated block 


;allocate segment 


;load allocated selector 
;pop to es register 


;initialize string offset 
;initialize block count variable 
;preserve block count 

;preserve string offset 


;recall string offset 
7;recall block count 


;block counter limit 
;string address 

;block offset in segment 
;preserve block count 
;preserve block offset 


;count limit for string 
;index for string/buffer 


;load from string 
;load buffer 
;increment string 
;increment block byte 


;block offset + block count 
block count 


'L', fo", 


Figure 3.15 The program suballo.asm, which suballocates a 16,384-byte segment 
into an 8192-byte block. 
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cmp di,dx ;check block limit 
pop di ;block offset + block count 
j1 LOOP1 


mov ax,1l ;set suballocation flag 
mov mflag,ax ;load 


@DosSubSet msell,mflag,msize 


@DosSubAlloc msell1,moffset,msizel 


pop di ;recall string offset 
pop si ;recall block count 


add di,8 ;go to "SUBALLOC" 

add si,2 ;increment word index 
cmp si,two ;compare second loop 
push si ;preserve block count 
push di ;preserve string offset 
jle LOOP4 


@DosFreeSeg msell 
@DosExit 1,0 
ENDP 


ENDS 
END 


Figure 3.15 (Concluded) 


Then 16,384 bytes are written in blocks of 8 bytes with “MEMORY ”. The serv- 
ice call 


@DosSubSet msell, mflag, msize 


initializes the segment for suballocation. Here msel1 is the allocated segment selec- 
tor; mflag is set to 1, indicating that a segment is being initialized; and msize is the 
original segment size. 

The call 


@DosSubAlloc msell, moffset, msizel 


returns an offset in the segment pointing to the start of the suballocated block whose 
size is msizel (in this case 8192 bytes). The parameter msell is, of course, the 
segment selector. 

Figure 3.16 illustrates the operation of this program based on CodeView out- 
put. In Figure 3.16a the initial load of the segment O06F:0000 to OO6F:3FFF is 
indicated. Here the end of the segment is demonstrated to contain“MEMORY ”. 
Next the suballocation is performed and in Figure 3.16b this is illustrated with 
“SUBALLOC” loaded up to address QOOF:2007. Note that there is a slight offset 
within the segment for the start of the suballocated block. This offset is 8 bytes and 
results in an overall shift by this number of bytes from the start of the segment. 
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= File Search View Run Watch Options Calls Trace! Go! SUBALLO. EXE 
er 


003F:0053 A10200 MOV AX,Word Ptr [0002] 
OO3F:0056 PUSH AX 
O03F:0057 MOV AX,Word Ptr [0004] 
PUSH AX 
A10000 MOV AX,Word Ptr [0000] 
50 PUSH AX 
9AO000A700 CALL O0O0A7: 0000 
A10200 MOV AX, Word Ptr [0002] 
50 PUSH AX 
B82F00 MOV AX, 002F 


>d es:0x3ff0 
>: 3SFFO 
> 4000 
> 4010 
> 4020 
>: 4030 
> 4040 
> 4050 
> 4060 


Search View Run Watch Options Calls Trace! Go! SUBALLO. EXE 


scam ican aaa aaa aaa: a aaa aa a 


A30400 Word Ptr [0004],AX 
AX,Word Ptr [0002] 
AX 
AX,Word Ptr [0004] 
AX 
AX,Word Ptr [0000] 
AX 

9AG000A700 O0A7: 0000 

A10200 AX,Word Ptr [0002] 


areeeneeeves ene seats oa reey te repeeternaes Heres ne teens. A terarenes re senreseves teeters | :ereetee ses ceted WRERTTECRORESe HTS LARET REO TETN Oe te the | pemeeee rene oe S ceameaitixand 


OO6F:0070 53 SUBALLOCSUBALLOC 
>d es:0x1iff0 
OO6F: 1FFO ‘ SUBALLOCSUBALLOC 
: 2000 SUBALLOC....RY 
> 2010 MEMORY MEMORY 
> 2020 MEMORY MEMORY 
> 2030 MEMORY MEMORY 
> 2040 MEMORY MEMORY 
' 2050 MEMORY MEMORY 
> 2060 MEMORY MEMORY 


(b) 


Figure 3.16 Facsimile CodeView output, illustrating (a) end of memory block for original 
allocation and (b) end of suballocated block with offset of 8 bytes. Cursor located in 
hidden portion of screen. (Courtesy of the Microsoft Corporation.) 
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3.3 MULTITASKING 


A major OS/2 enhancement (over DOS) is the ability to execute multiple tasks and 
segregate each task’s parameter space so that no mixing occurs. The OS/2 imple- 
mentation relies heavily on 80286 (and 80386) Protected Mode hardware features. 
Two threads, which exist as single entities with shared system resources, exist as 
stand-alone modules with their own system resources and can execute as separate 
tasks in Protected Mode. In this section we examine briefly the creation of threads 
and processes. 


3.3.1 Semaphores 


Before beginning our examination of task generation, however, it is necessary to 
consider synchronization. Assume, for example, that a given task depends on the 
outcome of a second task at some point in the first task’s execution. Clearly, when 
the first task is started it must be synchronized with the second task to ensure that 
the proper data become available when needed. If no requirement for synchroniza- 
tion exists, the two tasks can execute independently and are said to be asynchronous 
with respect to each other. 

A very important mechanism for achieving synchronization is the semaphore: 
RAM semaphores and system semaphores are considered in this book. A typical 
prescription for creating and accessing a RAM semaphore within a process (two 
threads) is as follows: 


Thread 1 
@DosSemSet sem_handle 
call to 2nd thread 
@DosSemWait sem_handle,-1l 
Thread 2 


activity to be synchronized 
@DosSemClear sem_handle 


Here the semaphore is set and the second thread called. Meanwhile the first thread 
waits for the semaphore to clear. When the second thread clears the semaphore, the 
first thread resumes execution. Only a handle, sem_handle, is used to pass informa- 
tion about the semaphore. This can be passed to a second independently compiled 
(or assembled) process via a shared memory area; however, in the illustration above 
it has been assumed that both threads are common to the same process and 
sem_handle appears in the process data area (as a double word). 
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System semaphores are used commonly between diverse processes and have 
the following general form: 


Data area 1 


no_excl dw 1 ;no exclusive 

aseml db ‘\SEM\SDAT.DAT,0 ssemaphore name 

sem_hdll dd 0 ;handle 

no _ to dd -1l ;no time out 
Process 1 

@DosCreateSem no excl, sem_hdll, aseml 

@DosSemSet sem _hdll 


call to execute 2nd process 


@DosSemWait sem_hdll,no_to 


and 


Data area 2 


aseml db ‘\SEM\SDAT.DAT’,0 ;semaphore common name 
sem _hdll dd 0 ;handle 
no_to dd -1 ;no time out 
Process 2 
@DosOpenSem sem hdll,aseml 


activity to be synchronized 


@DosSemClear  sem_hdll 


We see that the contrast between the two types is that system semaphores require a 
name and hence can be accessed from disjoint segments. RAM semaphores simply 
require a common handle. Fast-safe RAM semaphores are used by dynalink librar- 
ies. 


3.3.2 Creating a Thread 


Figure 3.17a is the flowchart for a program that generates two threads using RAM 
semaphores for synchronization. Figure 3.17b shows the actual code used in this 
process. The first thread clears the screen, writes message msg _ pO to the display, 
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SETUP 
DATA 


CLEAR 
SCREEN 


WRITE TTY 
MESSAGE #1 


BEEP #1 


SET 
SEMAPHORE 


CREATE 
THREAD #2 


BEEP #2 


WRITE TTY 
MESSAGE #2 


CLEAR 
SEMAPHORE 


WAIT CLEAR 
SEMAPHORE 


Figure 3.17a Flowchart for a program 
that generates two threads using RAM 


EXIT ca 
semaphores for synchronization. 
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TITLE CKTH1 -- Check thread generation (ckthl.asm) 


=e =e te Te Ne 


-sall 


-xlist 


-list 


errorl macro 


INCL BASE equ 1 
include os2def.inc 
include bse.inc 


local ERROR12 
or ax,ax 
jz ERROR12 

jmp ERROR11 


ERROR12: 
endm 


; 
dgroup GROUP 


STACK1 SEGMENT 


dw 
stklend equ 
STACK1 ENDS 


’ 
STACK SEGMENT 


dw 


STACK ENDS 


’ 
DATA SEGMENT 


, 
result 
action 


msg_poO 
db 
lmsg_p0O equ 
msg_pl db 
db 
db 
lmsg_pl equ 


msg_p2 a 
b 
db 


lmsg_p2 equ 
viohdl equ 


, 
freq 
duration 


° 
, 
e 
, 
° 
c 
e 
, 
° 
, 


Figure 3.17b Program illustrating two threads that use RAM semaphores for 


data 


WORD STACK 
1024 dup(?) 


"STACK1' 


WORD STACK 
1024 dup(?) 


"STACK! 


WORD PUBLIC 'DATA' 


0) 
1 


'This is the main OS/2 thread' 
ODH 
OAH 


$-msg_p0 


'This is a separate OS/2 thread! 
ODH 
OAH 


$-msg_p1 


DESCRIPTION: This routine verifies that a thread is 
generated. 


;Stack for threadi 


;Stack for main program 


;Exit code from main 
;Action code from main 


;Carriage return 
;Line feed 
;Length message zero 


;Carriage return 
;Line feed 
;Length message one 


‘An error occurred on thread open' 


ODH 
OAH 


$-msg_p2 
0 


daw 


thread1 


;Carriage return 
;Line feed 

;Length message two 
;Video handle 


75000 Hz 
7500 msec 


;Address threadl 


synchronization. The speaker is beeped and a message written. 
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stk_adrl 7End STACK1 
threadID ;threadi1 I.D. 
thd1_exit_code ;Thread 1 exit code 


thd_sem1l ;Semaphore threadl 
sem_hdll thd_seml ;Address thd_seml 
no_to =i ;No time out 


’ 

tr ;TOp row screen 
Le ;Left corner 

br ;Bottom row 

rc ;Right corner 


no_line ;Number blanked lines 
blank 7;Blank attribute 


ENDS 

SEGMENT WORD PUBLIC 'CODE' 

assume cs:CSEG,ds:dgroup,ss:STACK 
PROC FAR 


call cls 


@VioWrtTTY msg_p0,lmsg_p0,viohdl ;Write message one 
errorl 


@DosBeep freq, duration ;Beep speaker 
errorl 
@DosSemSet sem_hdll ;Set RAM semaphore 


errorl 


@DosCreateThread promadd, threadID,stk_adr1l 
errorl 
jmp CONT 
ERROR11: 
@VioWrtTTY msg_p2,1lmsg_p2,viohdl ;Write error message 
jmp ENDD 


@DosSemWait sem_hdll,no_to ;Wait for semaphore clear 


@DosExit action,result ;Exit 


OS21 ENDP 


thread PROC FAR 
@DosBeep freq,duration ;Beep speaker 
@VioWrtTTY msg_pl,lmsg_p1,viohdl ;Write message two 
@DosSemClear sem_hdll ;Clear semaphore 


@DosExit action,thd1_exit_code ;Exit threadl 


thread1l ENDP 


cls PROC NEAR 


’ 


@VioScrollUp tr,lc,br,rc,no_line,blank,viohdl 


Figure 3.17b (Continued) 
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Figure 3.17b (Concluded) 


beeps the speaker, sets a semaphore, turns on thread1, waits for the semaphore to 
clear, and exits the process. The second thread, thread1, beeps the speaker, writes 
msg _ pl to the display, clears the semaphore, and exits thread1. Synchronization is 
needed because both threads access the display and collisions will result if they run 
asynchronously. 

Figure 3.18a is the flowchart for a program that generates random boxes to the 
screen, one at a time. The program creates a box of random size (again, in our 
constraint of 200 x 200 pixels for CGA mode), erases the box, and continues (cre- 
ating and erasing boxes). The box creation occurs as a separate thread running 
asynchronously from the main thread. The main thread, once having turned on the 
box generator thread, simply waits for a keyboard input to terminate the process. 
Both threads run as part of the same process. 

The program code is presented in Figure 3.18b, where the main thread clears 
the screen, sets CGA mode and clears the screen again, locks the display and gets 
a selector to the physical screen buffer, beeps the speakers, turns on thread1, and 
waits for a keyboard input. Following a keyboard input, the screen is unlocked, 
standard mode resumed (80 x 25), the screen cleared again, and the process exited. 

Meanwhile the second thread, once started, first beeps the speaker and then 
enters an infinite loop. Within this loop a set of random box corners are generated 
and the box drawn on the display, as indicated above, with a call to boxx. The pixel 
(pel) attribute is set to unity for this call. Next, the box is erased by repeating the 
call with the pixel attribute set to zero. 

In general, the instruction 


@DosExit action, result 


will stop both threads from executing when called from the parent. This happens 
only in response to the keyboard input, which is sensed using @KbdStringIn. 

Figure 3.19 contains the support routines used by the box generating program: 
boxx, clsCGA, wdot, lineh, and linev. Note that some of the routines are slightly 
different from their counterparts given in GRAPHLIB.LIB (boxx is FAR, for ex- 
ample). Also, note that the second thread procedure is of distance attribute FAR 
even though it is defined within the same segment as the main thread. This allows 
the second thread to pass a full 32-bit address for its entry point. Multiple threads 
within the same process should be used when the task in question is reasonably 
simple and can be modularized within the same segment. 
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SETUP 
DATA 


CLEAR 
SCREEN 


SET CGA MODE AND 
CLEAR SCREEN 


LOCK SCREEN 
CONTEXT 


GET SELECTOR 
PHYSICAL BUFFER 


BEEP #1 


CREATE 
THREAD 


BEEP #2 


WRITE TTY 
MESSAGE #2 


CLEAR 
SEMAPHORE 


KEYBOARD 
HESITATE 


UNLOCK 
SCREEN 


SET STD 
MODE 


CLEAR 
SCREEN 


Figure 3.18a Flowchart for a program 
that generates single random boxes 


EXIT using multiple threads. 
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TITLE UNOS251 - This is the calling OS/2 program (UNOS251.ASM) 


=e te Se Se Se te 


- 8087 


’ 
EXTRN 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 


’ 


e 
Ul 


’ 
dgroup 
? 
STACK1 


stkiend 
STACK1 


STACK 


STACK 
DATA 
viohdl 
result 
action 
actionl 
tr 

lc 

br 

re 
no_line 
blank 

, 

CGAm 
lmodeE 
typeCGA 
colCGA 
txtcCGA 
txtrCGA 
hrCGA 
vrCGA 
STDm 
lmodes0 
types0 
cols0o 
txtcs80 
txtr8s0 


Figure 3.18b 


DESCRIPTION: This program "single" random plots boxes in protected 
mode. Graphics mode 05H is used to display the boxes. This routine 
employs multithreading to generate the boxs which are 

generated randomly (100 boxes in square 200 x 200). 


boxx: FAR, cC1SCGA: FAR 


viohdl,CGAm, lmodeE, typeCGA, colCGA 

txtcCGA, txtrCGA,hrCGA,vrCGA,STDm, lmode8s0, type80,col180 
txtc80,txtr80,hr80,vr80,waitf,dstat, PVBPtr1,bufst1,buflenl,physell 
MASK1,MASK11,OFFSET1, four, xx,dummy, two, xxx, eighty, row,col 
address1,x,y,xb,xe,ye, yb, Xxxx 


-sall 
-xlist 
INCL_BASE equ 1 
include os2def.inc 
include bse.inc 
-list 
GROUP data 
SEGMENT WORD STACK 
dw 1024 dup(?) 
equ $ 
ENDS 
SEGMENT WORD STACK ;Stack for thread 
dw 1024 dup(?) 
ENDS 
SEGMENT WORD PUBLIC 
equ 0) ;Required video handle 
dw fe) ;Completion code 
equ 1 ;Terminates current thread 
equ 0 ;Thread termination action 
dw 0 ;Top row screen clear 
dw 0 ;Left column screen clear 
dw 23 ;Bottom row screen clear 
dw 79 ;Right column screen clear 
dw 25 ;Number lines scrolled 
dw 0007H ;Blank character pair 
label FAR ;Video mode structure-CGA 
dw 12 ;Structure length 
db 00000111B ;Mode identifier 
db 2 ;Color option-Mode 5 
dw 40 ;text characters/line-ignore 
dw 25 ;text lines-ignore 
dw 320 shorizontal resolution 
dw 200 ;vertical resolution 
label FAR ;Video mode structure-80x25 
dw 12 ;Structure length 
db 00000001B ;Mode identifier-Mode 3+ 
db 4 ;Color option 
dw 80 ;text characters/line 
dw 25 ;text lines 
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hrs0o daw 
vr8s0 dw 


kbd_buf db 
lkbd_buf dw 
jowait dw 
kbdhdl equ 
waitf equ 
dastat dab 


PVBPtr1 label FAR 
bufst1 dd OB8000H 
buflenl dd 4000H 
physell dw 


MASK1 
MASK2 
MASK22 
MASK11 
OFFSET1 
four 

xx 
dummy 
two 


addressl 


4 
4 
4 
2 
2 
8 
0 
1 
¢ 
2 
da 
? 


thread1l 

- stklend 
threadID 0 

XXXX Setirce 
thd1_exit_code 0 


thd_sem1 fe) 
sem_hdll thd_sem1 
no_to =i 

freq 5000 
duration 


SEGMENT WORD PUBLIC 'CODE' 
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shorizontal resolution 
;vertical resolution 


;Keyboard buffer 
;Length keyboard buffer 
;Wait for CR 

;Keyboard handle 


;Screen waiting status 
;Returned status 


;Video buffer structure 
;Start physical address 
;Buffer length 

;0S/2 screen buffer selector 


;PEL byte mask 

;PEL byte mask--do 
;PEL byte mask--undo 
;Odd/even row mask 
;Odd row buffer offset 


;PEL attribute parameter 
780287 dummy "pop" 


;Output value 


;LOw 
;column 

;Address screen dot 
;random no. returned 


;Box col parameter 
;Box row parameter 
;Start column 

7End column 

;Start row 


;random seed 
s;address thread 

send of thread stack 
;thread ID 

box corner buffer 


sthreadl exit code 


;Semaphore thread1 
;Address thd_seml 

;No time out 

;frequency beep in Hz 
;duration beep in millisec 


assume cs:CSEG,ds:dgroup,ss:STACK 


PROC FAR 


call cls 


7;Clear screen 


Figure 3.18b (Continued) 
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yload 


threadl 
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@VioSetMode CGAm,viohdl 

call clsCGA 

@VioScrLock waitf,dstat,viohdl 
@VioGetPhysBuf PVBPtr1,viohdl 
push physell 
pop es 
@DosBeep 


freq,duration 


@DosCreateThread 


@KbdStringIn kbd_buf,1lkbd_buf, iowait, kbdhdl 


@VioScrUnlock viohdl 
@VioSetMode STDm,viohdl 
call cls 

@DosExit action,result 
ENDP 


PROC NEAR 


@VioScrollUp tr,lc,br,rc,no_line,blank,viohdl 


ret 
ENDP 


PROC NEAR 
mov bh,O 

mov bl,al 
mov xb,bx 
mov bh,0O 

mov bl,ah 
mov xe,bx 
ret 

ENDP 


PROC NEAR 
mov bh,0O 

mov bl,al 
mov yb,bx 
mov bh,0O 

mov bl,ah 
mov ye,bx 
ret 

ENDP 


PROC FAR 
@DosBeep freq,duration 


mov ax,one 
mov rndl1,ax 


lea bp, xxxx 


cx,4 
di,O 


;Set CGA graphics mode 
;Clear CGA screen 
;Lock screen context 
;Get physical buff sel 


7;Save selector 
;Load selector into es 


Chap. 


;Beep speaker 


prgmadd,threadID,stk_adrl 


s;hesitate 


7;Unlock screen 


780 x 25 alpha mode 


;Terminate process 


;Clear upper register half 
zal = start 

;Load xb less than 199 
;Clear upper register half 
;ah = end 

;Load xe less than 199 


;Clear upper register half 
jal = start 

;Load yb less than 199 
;Clear upper register half 
;ah = end 

;Load ye less than 199 


;Beep speaker 


;random seed 
;load r.n. parameter 


74 byte buffer 
sunterminated loop 


;box corner count 
7r.mn. memory index 


Figure 3.18b (Continued) 
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call ldmem ;load random memory values 
mov al,rndret ;move r.n. into register 
mov ds: [bptdi],al ;Save r.n. in memory 

inc di ;increment r.n. memory index 


loop LOOPOO 


mov al,ds:[bp] 7lst r.n. value 
mov ah,ds:[bp+1] ;2nd r.n. value 
cmp ah,al ;check 2nd different than ist 
jne EELSE1 ;jump if not equal 
mov al,170 ;move in arbitrary value 1.t. 200 
mov ah,180 ;move in different value 
call xload ;load xe and xb 


jmp IIF1l 


cmp ah,al ;check 2nd less than ist 
jle ELSE1 ;jump if less or equal 

call xload ;if g.t. calculate xb and xe 
jmp IIF1 


mov bl,al 72nd g.t. 
mov al,ah ;swap 
mov ah,bl ;reload 
call xload ;calculate xe and xb 


lst -- swap 


mov al,ds:[bpt+2] 73rd r.n. value 
mov ah,ds:[bp+3] 74th r.n. value 
cmp ah,al ;check 3rd different than 4th 
jne EELSE2 ;jump if not equal 
mov al,170 ;move in arbitrary value 1.t. 200 
mov ah,180 ;move in different value 
call yload ;load ye and yb 


jmp IIF2 


cmp ah,al ;check 4th less than 3rd 
jle ELSE2 ;jump if less or equal 

call yload ;if g.t. calculate yb and ye 
jmp IIF2 


mov bl,al f3rd g.t. 
mov al,ah ;Sswap 
mov ah,bl ;reload 
call yload ;calculate yb and ye 


4th -- swap 


push xb 
push xe 
push yb 
push ye 
mov al,MASK2 7;PEL value set 
mov MASK1,al ;load dummy 


;preserve box parameters 


call boxx swrite box 


pop ye ;recall box parameters 
pop yb 

pop xe 

pop xb 

mov al,MASK22 7;PEL value black 

mov MASK1,al ;load dummy 


call boxx sundo box 


jmp LOOPO ;jump unterminated loop 


@DosExit action1,thd1_exit_code 


Figure 3.18b (Continued) 
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thread1 ENDP 


ldmem PROC 


° 
’ 


NEAR 


push ax 
push bx 
push dx 


mov 
mov 
mov 
mul 
mov 
cle 
add 
adc 
mov 
div 
mov 
mov 
mov 


bx, 13849 


ax,bx 
adx,0 

bx, OFFFFH 
bx 

ax,ax 
rndl1,ax 
bx,350 


;load upper multiplicand 
;load previous r.n. 
;multiplier 


s;load additative constant 


;add lower order result 
;add carry if needed 
;load 2(16)-1 

;Calculate modulo 

;mov remainder into ax 
;save r.n. 

;scale r.n. less than 200 
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mov dx,0O ;clear upper dividend 
div bx 

mov ah,O 7;save al 

mov rndret,al ;returned value byte 
pop dx 

pop bx 

pop ax 

ret 

ENDP 


ENDS 
END OS21 


Figure 3.18b (Concluded) 


3.3.3 Creating Another Process 


When multiple processes are to be synchronized the system semaphores are appro- 
priate. System semaphores provide a common link between the two processes 
through the semaphore name. If RAM semaphores are used, the semaphore handle 
must be shared with a common data element. Figure 3.20a illustrates a program that 
generates two processes using system semaphores for synchronization. The sema- 
phore name must be zero terminated and preceded by 


eNSEM aw 0°? 
In Figure 3.20b we illustrate this naming with a semaphore called 
‘\SEM\SDAT.DAT’, 0 


and given the variable name asem1. 
The second process called by the program in Figure 3.20b is OS2P2.EXE, as 
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TITLE NNOS252 - Supplemental routines for box plotting (NNOS252.ASM) 


DESCRIPTION: These routines set up box plots in CGA mode. Graphics 
mode 05H is used to display the box. This set of routines 

is called by box plotting main routine. The boxes are created or 
destroyed depending on MASK1 value. 


=e se “=e “e Se TO 


-sall 


-xlist 
INCL _BASE equ 1 
include os2def.inc 
include bse.inc 

sist 


EXTRN viohdl1: WORD 

EXTRN CGAm: FAR, lmodeE: WORD, typeCGA: BYTE 

EXTRN ColCGA: BYTE, txtcCGA: WORD, txtrCGA: WORD, hrCGA: WORD, vrCGA: WORD 

EXTRN STDm: FAR, lmode80:WORD, type80: BYTE, col180: BYTE, txtc80:WORD, txtr8s0:WORD 
EXTRN hr80:WORD,vr80:WORD 

EXTRN waitf:WORD,dstat: BYTE, PVBPtr1: FAR, bufst1: DWORD 

EXTRN buflen1: DWORD, physell1: WORD, MASK1: BYTE, MASK11: WORD, OFFSET1: WORD 
EXTRN four:WORD,xx:WORD, dummy: WORD, two: BYTE, xxx: BYTE, eighty: WORD 

EXTRN row:WORD,col:WORD, address1:WORD,x:WORD, y:WORD, xb: WORD, xe: WORD 

EXTRN yb: WORD, ye: WORD 


? 
CSEG SEGMENT WORD PUBLIC 'CODE'! 
PUBLIC boxx,clsCGA 

assume cs:CSEG 


boxx PROC FAR 


; xb = x-begin,xe = x-end,yb = y-begin,ye = y-end 


push ax 
push bx 
push cx 
push dx 


mov ax,xb 
cmp ax,xe 
jl ELSE10 
xchg ax,xe ;Swap xb and xe 
mov xb,ax 


;Check xb 1.t. xe 


mov ax,yb 

cmp ax,ye 

j1 ELSE11 
xchg ax,ye ;Swap yb and ye 
mov yb,ax 


;Check yb 1.t. ye 


ELSE11: 


mov ax,yb :Top box line 

mov y,ax 

call lineh ;Draw top horizontal line 
mov ax,ye ;Bottom box line 

mov y,ax 

call lineh ;Draw bottom horizontal line 
mov ax,xb ;Left box line 

mov x,ax 

call linev ;Draw left vertical line 
mov ax,xe ;Right box line 

mov x,ax 

call linev ;Draw right vertical line 


Figure 3.19 Associated support routines for the “single” random box program. 
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pop dx 
pop cx 
pop bx 
pop ax 
ret 

boxx ENDP 


; 
ClsCGA PROC FAR 


° 
’ 


@VioScrLock waitf,dstat,viohdl ;Lock screen context 
@VioGetPhysBuf PVBPtri1,viohdl ;Get physical buffer 
push physell ;Screen selector 
pop es ;Load extra segment 


mov bp,0O ;Start offset zero 
mov al,O ;Zero attribute-clear 


mov es:[bp],al 
inc bp 
cmp bp,1F3FH ;Check end ist buffer 
jle Dol 


;Clear byte 


mov bp,2000H ;Offset 2nd buffer-odd 
mov al,O ;Zero attribute-clear 


mov es:[bp],al ;Clear byte 
inc bp 
cmp bp,3F3FH ;Check end 2nd buffer 


jle DOo2 


@VioScrUnLock viohdl Unlock screen context 


ret 
ENDP 


clsCGA 


PROC NEAR 


(col,row) = (x,y) 


push ax 
push bx 
push cx 
push dx 
push bp 


fild four ;Load stack with 
fild col 7ST = col, ST(1) = 4 


fprem ;Modulo 

fistp xx ;Store remainder in xx 
fistp dummy ;Pop stack 

mov al,3 

mov bl,byte ptr xx 

sub al,bl 7(3 - col % 4) 

mov ah,O ;Clear upper multiplicand 
mul two 

mov cl,al ;Shift value for PEL 
mov al,MASK1 ;PEL color mask 

shl al,cl ;Shift to correct PEL 
mov xxx,al ;Store buffer value 


° 
' 


Mov ax,row ;Begin address calculation 
shr ax,1 ;Divide row by 2 

mov dax,0 ;Clear upper multiplicand 
mul eighty 


Figure 3.19 (Continued) 
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mov bx,col 

shr bx,1 

shr bx,1 

add ax,bx 

mov address1,ax 

mov ax,row 

and ax,MASK11 

cmp ax,0 

jle ELSE1 
mov ax,addressl 
add ax,OFFSET1 
jmp IF11 


mov ax,addressl 


mov bp,ax 
mov al,xxx 


cmp al,0 

je ccc 
or es:[bp],al 
jmp DDD 


mov es:[bp],al 


pop bp 
pop dx 
pop cx 
pop bx 
pop ax 


ret 
ENDP 


PROC NEAR 


y = row position, xb = begin, xe 


push ax 
push bx 
push cx 
push dx 


MOV ax,y 

cmp ax,199 

jg LINE1 
mov row,ax 
jmp LINE2 


mov ax,180 
mov row,ax 


mov ax,xb 


mov col,ax 
push ax 
cmp ax,319 
jle LINE3 
mov ax,319 
mov col,ax 


call wdot 
pop ax 
inc ax 
cmp 

jle 


;Convert column value to bytes 


;offset in ax 

;Save offset base 
;Check even/odd row 
;Look for bit 0 set 


s;add odd buffer offset 


s;screen buffer address 
;Attribute value for dot 


;check PEL black (0) 


;Write dot 


;Clear PEL 


= end 


;Establish row for wdot 
;check row 1.t. 199 
;jump if greater 

;load "row" 


;load arbitrary value 1.t. 


s;load "row" 
sEstablish start column 
7;Save column value 


;check col less than 319 
sjump if 1.t.e6. 319 


;if greater load arbitrary value 


s;load "col" 


;Write dot (col,row) 
;Recall column 
;Increment column 


;Check end horizontal line 


’ 


Figure 3.19 (Continued) 
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pop dx 
pop cx 
pop bx 
pop ax 


ret 
ENDP 


PROC NEAR 
x = col position, yb = begin, ye = end 


push ax 
push bx 
push cx 
push dx 


mov ax,xX ;Establish column for wdot 
cmp ax,319 ;check col 1.t. 319 
jg LLINE1 ;jump if greater 
mov col,ax z;load "col" 
jmp LLINE2 
LLINE1: 
mov ax,319 ;greater therefore arbitrary value 
mov col,ax jload "col" 


LLINE2: 


mov ax,yb ;Establish start row 


DO20: 
mov row,ax 
push ax ;Save row value 
cmp ax,199 ;check row value g.t. 199 
jle LLINE3 ;jump if less 
mov ax,199 ;greater therefore arbitrary value 
Mov row,ax ;load "row" 
LLINE3: 
call wdot ;Write dot (col,row) 
pop ax ;Recall row 
inc ax ;Increment row 
cmp ax,ye ;Check end vertical line 
jle DO20 
pop dx 
pop 
pop bx 
pop ax 


ret 
ENDP 


ENDS 
END 


Figure 3.19 (Concluded) 


specified under prgrm_nm in the parameter list for @DosExecPgm. The process 
indicated in Figure 3.20b clears the screen, writes msg_p0 to the display, creates a 
system semaphore with handle sem_hdl1 and name SDAT.DAT, beeps the speaker, 
sets the semaphore, and turns on the second process. Following this, the process 
waits for the system semaphore to clear and then terminates both the second proc- 
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SETUP 
DATA 


CLEAR 
SCREEN 


WRITE TTY 
MESSAGE 


CREATE 
SEMAPHORE 


BEEP #1 


SET 
SEMAPHORE 


CREATE 
PROCESS #2 


PROCESS #2 


WAIT CLEAR 
SEMAPHORE 


KILL 
PROCESS #2 


Figure 3.20a Flowchart for program 
that generates two processes using 


EXIT 
system semaphores. 


ess and itself. Note that this main process accesses the screen at several points (cls 
and @ViowrtT TY). 

Figure 3.21a illustrates the flowchart for the child process, 
OS2P2.ASM, turned on by the program in Figure 3.20b. The supporting code is 
shown in Figure 3.21b. The common semaphore name, “\SEM\SDAT.DAT”’, 0, is 
again defined by a variable asem1 (not related by symbol to the asem1 appearing in 
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TITLE CKPR1 -- Check thread generation (ckprl.asm) 


generated. 


~e Se te Se Se 


-sall 


~X1ist 
INCL _ BASE equ 1 
include os2def.inc 
include bse.inc 
-list 
errorl macro 
local ERROR12 
or ax,ax 
jz ERROR12 
jmp ERROR11 
ERROR12: 
endm 


dgroup GROUP 


data 
STACK SEGMENT WORD 
dw 

ENDS 


STACK 
1024 dup(?) 


"STACK" 
STACK 


’ 
DATA 


result dw 0 
action equ i | 


SEGMENT WORD PUBLIC 'DATA' 


msg_pO db 
db 
db 


lmsg_pO equ 


'This is the main OS/2 thread' 
ODH 
OAH 


$-msg_p0 
viohdl equ 


freq 
duration 


no_excl 
aseml 
sem_hdll 
no_to 


tr 

le 

br 

rc 
no_line 
blank 


DESCRIPTION: This routine verifies that a process is 


;Stack for main program 


;Exit code from main 
;Action code from main 


;Carriage return 
;Line feed 
;Length message zero 


;Video handle 


74000 Hz 
7500 msec 


;no exclusive 

;Name system semaphore 
;Address thd_seml 

;No time out 


;Top row screen 

;Left corner 

;Bottom row 

;Right corner 

;Number blanked lines 
;Blank attribute 


Figure 3.20b Program that generates two processes using system semaphores. 
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obj_name_buf 
lobj_name_buf 
async 

argptr 

envptr 

pid 


prgm_nm 


DATA 
; 


CSEG 


ENDS 


assume 


PROC FAR 


OS21 


call cls 


@VioOWrtTTY 
errorl 


@DosCreateSem 
errorl 


@DosBeep 


@DosSemSet 
errorl 


SEGMENT WORD PUBLIC 
cs:CSEG,ds:dgroup,ss:STACK 


10 dup(?) 
$-obj_name_buf 


OS2P2.EXE',0 


"CODE' 


msg_p0,1lmsg_p0,viohdl 


no_excl,sem_hdll,aseml 


freq,duration 


sem_hdll 


;Process name buffer 
;length buffer 
;asynchronous operation 
;pointer arguments 
;environment pointer 
;process ID 


;process name 


;Clear screen 


;Write message 


;Create system semaphore 


;Beep speaker 


;Set semaphore 


;Create child process 


@DosExecPgm obj name_buf,lobj_ name _buf,async,argptr,envptr,pid,prgm_nm 


errorl 


@DosSemWait 


sem_hdli1,no_to 


@DosKillProcess 1,pid 


ERROR11: 


@DosExit action,result 


ENDP 


PROC 


@VioScrollUp 


ret 
ENDP 


ENDS 
END 


;Wait for semaphore clear 


;Terminate child process 


;Exit 


;Clear screen 


tr,1lce,br,re,no_line,blank, viohdl 


Figure 3.20b 


(Concluded) 
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OPEN 
SEMAPHORE 


WRITE TTY 
MESSAGE 
CLEAR 
SEMAPHORE 


Figure 3.2la Flowchart for a child 
process, illustrating synchronization 
using system semaphores. 


the parent). This child process opens the semaphore, beeps the speaker, writes a 
message msg pl to the display, and clears the semaphore. The process then termi- 
nates itself. Synchronization is needed because both processes access the display. 

This very brief example presents the use of multiple processes that must be 
synchronized. Earlier we used flags in a common data area to accomplish this with 
the program that displayed 100 random boxes at once. The use of semaphores is a 
more formal and elegant way to achieve synchronization and does not require 
a constant polling of the flag to check for process completion. The system does this 
for us. 
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TITLE OS2P2 -- Check thread generation (os2p2.asm) 


=e “ese te “8 Te 


=e 


’ 


errorl 


ERROR12: 


, 
dgroup 
; 
STACK1 


STACK1 


, 
DATA1 


a 
result 
action 


msg_pl 


lmsg_pl 


viohdl 


freq 


DESCRIPTION: This routine verifies that a 2nd process is 
generated. It uses semaphores for synchronization. 


-sall 


-Xlist 
INCL _ BASE equ 1 
include os2def.inc 
include bse.inc 
«List 


macro 
local ERROR12 
or ax,ax 
jz ERROR12 
jmp ERROR11 


endm 

GROUP datal 

SEGMENT WORD STACK '"STACK1'! ;Stack for 2nd process 
dw 1024 dup(?) 

ENDS 

SEGMENT WORD PUBLIC 'DATA1' 


dw 0 ;Exit code from process 
equ A ;Action code from process 


db 'This is a separate OS/2 process' 

db ODH ;Carriage return 

db OAH ;Line feed 

equ $-msg_pl ;Length message one 
equ ;Video handle 


75000 Hz 


duration 7500 msec 


Figure 3.21b Child process, illustrating synchronization using system semaphores. 


;Semaphore name 
;Address thd_seml 
;No time out 


ENDS 


SEGMENT WORD PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup,ss:STACK1 
PROC FAR 


@DosOpenSem sem_hdll1,aseml ;Open system semaphore 
errorl 


@DosBeep freq,duration ;Beep speaker 
errorl 
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@VioWrtTTY msg_pl1,lmsg_p1,viohdl ;Write message 
errorl 


@DosSemClear sem_hdll ;Clear semaphore 


ERROR11: 
@DosExit action,result ;Exit process 


OS21 ENDP 
CSEG ENDS 
END 


Figure 3.21b (Concluded) 


3.4 INTERPROCESS COMMUNICATIONS 


We have seen examples of interprocess communication (IPC) using shared memory 
and semaphores. OS/2 has three additional mechanisms for achieving such commu- 
nication: pipes, queues, and signals. Signals basically act like a hardware interrupt 
and tend to reflect rather specialized interprocess communications [5]. We only 
mention them. The dominant mechanisms we focus on in this book are the remain- 
ing four. Synchronization is a major requirement for processes competing for serial 
mechanisms [6]. OS/2 solves this problem in a number of ways. 


3.4.1 Pipes and Queues 


A flowchart for a parent program that passes messages via pipes is illustrated in 
Figure 3.22a. The code associated with the parent is presented in Figure 3.22b. This 
program employs several IPC mechanisms in addition to pipes: semaphores, for 
achieving synchronization, and shared memory, for passing the pipe handle and 
message length. First the screen is cleared with a call to cls. Next, the shared seg- 
ment is created and this segment is arbitrarily large (512 words). The call to 
@DosMakePipe creates the pipe with a read handle, read_hdl, and a write handle, 
write hdl. The parameter pflag specifies the pipe length in bytes. 

Note that a pipe is anonymous in this context and serves simply as a high- 
speed buffer area with no name. A system semaphore is created, the speaker beeped, 
the message msg _p0O written to the pipe buffer using write_hdl, the semaphore set, 
and a child process executed. The parent then waits for the child to execute and 
clear the semaphore before it terminates the child and exits. 

Figure 3.23a presents the flowchart for the child process. Figure 3.23b contains 
the code for this process. Initially, the child opens the semaphore, beeps the speaker, 
and gets a selector to the shared segment. This shared segment is used to obtain a 
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SETUP 
DATA 


CREATE SHARED 
SEGMENT 


CREAT 
PIPE 


PIPE READ HANDLE IN 
SHARED SEGMENT 


CREATE 
SEMAPHORE 


BEEP 


WRITE MESSAGE 
TO PIPE 


SET 
SEMAPHORE 


CREATE 
CHILD 


CHILD 
PROCESS 
WAIT CLEAR 
SEMAPHORE 


KILL 
PROCESS 


Figure 3.22a Flowchart for a main 
program that examines pipes for 


EXIT ee? 
interprocess Communication. 
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TITLE PIPEST -- Check pipe generation (pipest.asm) 


=e Se Se Se 


-sall 


=e 


-xlist 


-list 
errorl macro 


INCL_BASE equ 1 
include os2def.inc 
include bse.inc 


local ERROR12 


or ax,ax 
jz ERROR12 
jmp ERROR11 
ERROR12: 
endm 
dgroup GROUP data 
’ 
STACK SEGMENT WORD STACK "STACK! 
dw 1024 dup(?) 
STACK ENDS 
’ 
DATA SEGMENT WORD PUBLIC 'DATA' 
’ 
result dw fe) 
action equ 1 
msg_pO db 'This is the OS/2 pipe message' 
db ODH 
db OAH 
lmsg_pO equ $-msg_pO 
viohdl equ 0 
freq dw 4000 
duration dw 500 
; 
Hi ee a ee eee 
; Semaphore 1 parameters 
no_excl dw 1 
aseml db '\SEM\SDAT.DAT',0 
sem_hdll dd 0 
no_to dd =J. 
Geet nee nnn = 
: 
ps dw fe) 
lc dw 0 
br dw 23 
rc dw 79 
no_line dw 25 
blank dw 0007H 


=e 7e Se Se Me Fe 


DESCRIPTION: This routine verifies that a pipe is 
generated. 


;Stack for main program 


;Exit code from main 
;Action code from main 


;Carriage return 
;Line feed 
;Length message zero 


;Video handle 


74000 Hz 
7500 msec 


;no exclusive 

;Name system semaphore 
;Address 

;No time out 


7;Top row screen 

;Left corner 

;Bottom row 

;Right corner 

;Number blanked lines 
;Blank attribute 


Figure 3.22b Pipe main program. 
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obj_name_buf dd 10 dup(?) ;Process name buffer 
lobj_name_buf dw $-obj_name_buf ;length buffer 
async dw 1 ;asynchronous operation 
argptr dw fe) ;pointer arguments 
envptr dw 0 ;environment pointer 
pid dw a ;process ID 

dw ? 
prgm_nm db 'PIPECL. EXE',0 ;process name 
: 
: Pipe Parameters 
read_hdl dw ? ;Pipe read handle 
write_hdl dw ? ;Pipe write handle 
pflag dw 256 ;Pipe length in bytes 
bytes written dw ? ;bytes written to pipe 
; Shared Memory Parameters 
msize dw 512 ;Shared buffer size 
msell dw ? ;Shared selector 
shrname db '\ SHAREMEM\SDAT1.DAT',0 ;Shared buffer name 
; 
; 
zero dw 0 
one dw iL 


, 
DATA ENDS 
; 
CSEG SEGMENT WORD PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup,ss:STACK 
0S21 PROC FAR 


call cls ;Clear screen 


@DosAllocShrSeg msize,shrname,msell 


errorl 

push msell ;preserve selsctor 

pop es ;selector in extra segment 
mov bp, zero ;index equal 0 


se 


@DosMakePipe read_hdl,write_hdl,pflag ;Create pipe 


errorl 
mov ax,read_hdl ;transfer read handle 
mov es: [bp+2],ax shandle in extra segment 


@DosCreateSem no_excl,sem_hdll,aseml ;Create system semaphore 
errorl 


@DosBeep freq, duration ;Beep speaker 


@DosWrite write_hdl,msg_p0,lmsg_p0O,bytes_written 


errorl 

mov ax,bytes_written ;transfer message length 
mov es: [bp+4],ax ;length in buffer 
@DosSemSet sem_hdll ;Set semaphore 

errorl 


Figure 3.22b (Continued) 
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;Create child process 
@DosExecPgm obj_name_buf,lobj_name_buf,async,argptr,envptr,pid,prgm_nm 
errorl 


@DosSemWait sem_hdll1,no_to ;Wait for semaphore clear 


. 
’ 


@DosKillProcess 1,pid ;Terminate child process 


ERROR11: 
@DosExit action,result eEXIt 


ENDP 
PROC 


;Clear screen 
@VioScrollUp tr,lc,br,rc,no_line,blank,viohdl 


ret 
ENDP 


ENDS 
END 


Figure 3.22b (Concluded) 


OPEN 
SEMAPHORE 


ADDRESS SHARED 
SEG. FOR PIPE HANDLE 
READ MESSAGE #1 
FROM PIPE 
WRITE TTY 
MESSAGE #1 
CLEAR 
SEMAPHORE 


Figure 3.23a Flowchart for a child 
process that illustrates pipes used for 
interprocess communications. 
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TITLE PIPECL -- Check pipe generation (pipecl.asm) 


DESCRIPTION: This routine verifies that a pipe is 
generated. It uses semaphores for synchronization. 


se se te te Te 


-sall 


se 


«Xlist 
INCL BASE equ 1 
include os2def.inc 
include bse.inc 


List 
7 
errorl macro 
local ERROR12 
or ax,ax 
jz ERROR12 
jmp ERROR11 
ERROR12: 
endm 
Ld 
dgroup GROUP datal 
, 
STACK1 SEGMENT WORD STACK 'STACK1' ;Stack for 2nd process 


dw 1024 dup(?) 
STACK1 ENDS 


DATA1 SEGMENT WORD PUBLIC 'DATAI1' 
result dw 0 ;Exit code from process 
action equ 1 ;Action code from process 


viohdl equ 0 ;Video handle 
freq dw 5000 75000 Hz 
duration dw 500 7500 msec 

? ee ee ee cee ee ee ee ee ee ee ee ee ee ee ce ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 

; Semaphore parameters 

asenl db '\SEM\SDAT.DAT',0 ;Semaphore name 
sem_hdl1l dd 0 ;Address 
no_to dd = ;No time out 
1 ee 
zero dw 0 

; 

? ame i i ae ee 

; Shared Buffer Parameters 

? — ee ee ee ee ee ee ee ee ee em ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee oe em oe oe oe oe oe oe ee 


shrsel dw 
shrname db 


; 
read_hdl 


lmsg 
buffer 


dw ? 
dw ? 
db 256 dup(?) 


;selector 
s;buffer name 


;read handle 
;length message 
;buffer length 


Figure 3.23b Routine for a child process, illustrating pipes for interprocess 
communications. 
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;actual bytes read 


ENDS 


SEGMENT WORD PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup,ss:STACK1 
PROC FAR 


@DosOpenSem sem_hdll1,aseml ;Open system semaphore 
errorl 


@DosBeep freq,duration ;Beep speaker 
errorl 


@DosGetShrSeg shrname,shrsel ;shared segment 
errorl 

push shrsel ;preserve selector 
pop es ;load extra segment 
mov bp, zero ;initialize index 
mov ax,es: [bp+2] ;read handle 

mov read_hdl,ax ;specified 

mov ax,es: [bp+4] ;message length 
mov lmsg,ax ;specified 


@DosRead read_hdl,buffer,1lmsg,bytes_read 
errorl 


@VioWrtTTY buffer,1lmsg,viohdl ;Write message 
errorl 


@DosSemClear sem_hdll ;Clear semaphore 


ERROR11: 
@DosExit action, result ;Exit process 


O0S21 ENDP 
CSEG ENDS 
END OS21 


Figure 3.23b (Concluded) 


read handle and the message length for the pipe. The pipe is then read using 
@DosRead and the message loaded into buffer. The display is then updated with the 
message content using 


@VioWrtTTY buffer, lmsg, yiohdl 


where Imsg is the message length in bytes and viohdl the display handle. It is this 
access of the display that requires synchronization with the parent. 

Following the message write to the screen, the semaphore is cleared and 
the child process terminates execution. The key step in this code was to 
ensure that common pipe link exists between the routines. Unlike the sema- 
phore link, which uses a commonly named area (‘\SEM\SDAT.DAT’,0) across both 
the child and parent, the pipe handle was passed via a common memory area 
(‘\SHAREMEM\SDAT1.DAT’,0). 


Sec. 3.4 Interprocess Communications 157 


Figure 3.24a illustrates the main process for a set of programs that demonstrate 
queue operation. Figure 3.24b presents the associated code for this parent process. 
The process opens with a call to @DosCreateQueue. The common link between the 
child and parent is the queue name, ‘\QUEUES\QDAT.DAT’,0. This call returns a 
queue handle, q_hdl. The speaker is beeped and a child process (named 
‘QUEUECL.EXE’) turned on. The queue is used to pass a 32-bit buffer address 
from the child process to the parent. The selector value of this address is loaded into 
es and the offset into bx. This buffer address is contained in the double word 
buffer1. 


SETUP 
DATA 


CREATE 
QUEUE 


CREATE 
PROCESS 


PROCESS 


READ QUEUE 
BUFFER ADDRESS 


TRANSFER QUEUE 
BUFFER DATA TO 
PARENT BUFFER 


FREE QUEUE 
BUFFER AREA 


CLOSE 
QUEUE 


WRITE TTY 
MESSAGE 


KILL 
PROCESS 


Figure 3.24a Flowchart for a main 
program, illustrating queues for 


EXIT : — 
interprocess communications. 
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TITLE QUEUEST -- Check queue generation (queuest.asm) 
; 
; DESCRIPTION: This routine verifies that a queue is 
; generated. 
-sall 
sx1ist 


INCL BASE equ 1 

include os2def.inc 

include bse.inc 
-list 


e 
’ 


errorl macro 
local ERROR12 
or ax,ax 
jz ERROR12 
jmp ERROR11 
ERROR12: 
endm 


dgroup GROUP data 

; 

STACK SEGMENT WORD STACK "STACK' 
dw 1024 dup(?) 

STACK ENDS 


DATA SEGMENT WORD PUBLIC 'DATA' 


Ul 


result dw 0 

action equ 1 

viohdl equ 0 

freq dw 4000 
duration dw 500 
selector dw 2 


obj_name_buf dd 
lobj_name_buf dw 


10 dup(?) 
$-obj_name_buf 


async dw 1 
argptr dw 0 
envptr dw 0 
pid dw Bee 


prgm_nm db 


’ 


'QUEUECL. EXE',0 


ee me =e se te Ne 


q_ hdl dw ? 


q prty dw 

q_ name db '\QUEUES\QDAT.DAT' ,0 
request dd 0 

el _prty dw fe) 

asemi dd 0) 

el _ code dw 0 


Chap. 3 


;suppresses macro lists 


;Suppresses source list 
;sets IBM macro flag 
;0s2 definitions 
;Dos,Vio,Mou, & Kbd 
;turns list on 


;exit macro 

;local macro label 

;set ax bits 

;jump if zero next instruction 
;otherwise exit process 

7;end macro 


;data and extra group 


;Stack for main program 


;Exit code from main 
;Action code from main 


;Video handle 


74000 Hz 
7500 msec 
allocated segment selector 


;Process name buffer 
;length buffer 
;asynchronous operation 
;pointer arguments 
;environment pointer 
;process ID 

;process name 


;Queue handle 

;Queue ordering priority 
;name 

;Read request parameter 
;Element read priority 
;semaphore 

;element code 


Figure 3.24b Main program illustrating queues. 
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no_wait dw 0 ;wait processing 

lmsg dw Fs ;message length--read 
bufferl dd fe) ;queue buffer address 
buffer 2 ;read buffer 


SEGMENT WORD PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup,ss:STACK 
PROC FAR 


@DosCreateQueue q_hdl,q prty,q name 
errorl 


;Create queue 


@DosBeep freq,duration ;Beep speaker 


;Create child process 
@DosExecPgm obj _name_buf,lobj_name_buf,async,argptr,envptr,pid,prgm_nm 
errorl 


;read queue buffer area 
@DosReadQueue q_ hdl,request,1msg,bufferl,el_code,no_wait,el_prty,asemi 
errorl 


mov bx,word ptr bufferl ;child buffer 32-bit address 
mov ax,word ptr bufferl+2 ;selector 

mov selector,ax 

push selector 


pop es ;extra segment register 
lea bp,buffer ;load data buffer address 
mov cx,lmsg ;count limit 

mov di,O ;count index 


mov al,es: [bx+di] ;transfer from queue area 
mov ds: [bpt+di],al ;transfer to ds buffer 
inc di ;increment index 


loop LOOP1 


@DosFreeSeg selector ;free allocated segment 
errorl 


@DosCloseQueue q_hdl ;close queue 


@VioWrtTTY buffer,1lmsg,viohdl 
errorl 


;write message to screen 


@DosKillProcess 1,pid ;Terminate child process 
ERROR11: 

@DosExit action,result ;Exit 
0S21 ENDP 
CSEG ENDS 

END 


Figure 3.24b (Concluded) 


Next, the length of the buffer is loaded into a loop counter. This value, Imsg, 
was retrieved from the child process along with bufferl using an @DosReadQueue 
call. The contents of the buffer pointed to by bufferl are loaded into the buffer, and 
the segment area pointed at by selector, the segment address associated with the 
pointer, bufferl, is released. This segment was allocated previously, during execu- 
tion of the child process, as we shall see shortly. The queue is closed and the mes- 
sage in buffer written to the screen. Finally, the child is terminated and the parent 
exits back to OS/2. 
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Figure 3.25a shows the flowchart for the associated child process and Figure 
3.25b the corresponding code. The child opens with a beep to the speaker alerting 
the user that the child has started. Next, the queue is opened (note that the queue 
name represents the common link between the two processes. At this point the 
child allocates a segment using @DosAllocSeg. The size of the segment equals the 
message length and it is a giveable segment (aseg give=1). The segment allocated 
has a selector returned (q_w) which is loaded into es and the contents of the mes- 
sage written to this buffer. The speaker is beeped with a slightly different tone, 
@DosGiveSeg executed (which returns a selector that can be given back to the 
parent, q_rr), and the 16-bit read selector loaded into the segment portion of a 32- 
bit pointer to the giveable segment (q_r). 

A macro @DosWriteQueuel has been defined at the beginning of the program 
and this macro has the fifth statement as pushing a 32-bit value (not address) onto 
the stack prior to the call to DOSWRITEQUEUE. This macro is called to transfer 


BEEP #1 


ALLOCATE QUEUE 
BUFFER AREA 
LOAD 
MESSAGE 
BEEP #2 
PERMIT ACCESS TO 
QUEUE BUFFER 


Figure 3.25a Flowchart for a child 
process, illustrating queues for 
interprocess communications. 
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TITLE QUEUECL -- Check queue generation (queuecl.asm) 


DESCRIPTION: This routine verifies that a queue is 
generated. It uses semaphores for synchronization. 


INCL BASE equ 1 
include os2def.inc 


;Suppress macro listing 


;Suppress source list 
;set IBM macro flag 
;include os2 macros 


include bse.inc ;Dos,Vio,Mou, & Kbd 
-list ;turn list on 


e 
, 


errorl macro ;exit macro 
local ERROR12 ;local macro label 
or ax,ax ;set ax 
jz ERROR12 ;jump to next instruction 
jmp ERROR11 ;exit 
ERROR12: 
endm 7;end macro 
;Corrected macro 
@DosWriteQueuel macro handle, request, length,data,prty 
@define DOSWRITEQUEUE ;;define API call 
@pushw handle ;;push word handle 
@pushw request ;;push word request 
@pushw length ;;push buffer length 
@pushd data ;;push 32-bit address 
@pushw prty ;7push priority 
call far ptr DOSWRITEQUEUE 7;7;call API function 
endm 


;load ds and es 


dgroup GROUP datal 


, 

STACK1 SEGMENT WORD STACK 'STACK1'! 
dw 1024 dup(?) 

STACK1 ENDS 


’ 
DATA1 SEGMENT WORD PUBLIC 'DATA1' 


*Stack for 2nd process 


result dw ;Exit code from process 
action equ ;Action code from process 


freq 75000 Hz 
freql 72000 Hz 
duration 7500 msec 


q_hdl : ;queue handle 

q pid ;process ID--queue creator 
q_ name ;name 

request ;write request parameter 
prtyo ;priority message 1 


msg_pO db 'This is a priority 1 message',0ODH, OAH 
lmsg_pO dw $-msg_pO ;length 


c 


Figure 3.25b The child process, illustrating queues for interprocess 
communications. 
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aseg_give 


qr 
q rr 


, 
DATA1 


’ 
CSEG 


0S21 


’ 


LOOP1: 


ERROR11: 
0S21 
CSEG 


ENDS 


SEGMENT WORD PUBLIC 'CODE' 
assume cs:CSEG,ds:dgroup,ss:STACK1 
PROC FAR 


@DosBeep 
errorl 


freq,duration 
@DosOpenQueue q pid,q hdl,q name 
errorl 


@DosAllocSeg 
errorl 


lmsg_p0,q_w,aseg give 


push q w 

pop es 

lea bx,msg_p0 
mov cx,lmsg_pO 
mov di,O 


mov al,ds: [bx+di] 
mov es:[di],al 
inc di 

loop LOOP1 


push ds 
pop es 


@DosBeep 
errorl 


freql,duration 


@DosGiveSeg 
errorl 


q_w,q pid,q rr 


lea bx,q r 
mov ax,q rr 
mov ds: [bx+2],ax 


;queue write selector 


;allocated segment giveable 


;queue read 32-bit pointer 
;queue read selector 


;Beep speaker 


;Open queue 


allocate segment 


;allocated segment selector 


Chap. 


;pop to extra segment register 


;offset of message 
;loop count=message length 
;zero index 


;transfer message 
;message to extra segment 
;increment index 


;reload ds to stack 
7;es=ds 


;2nd beep 


;get selector 


;32-bit read address 

716-bit read selector 
;load read address 

;write address to queue 


@DosWriteQueuel q hdl,request,lmsg_p0,q r,prty0 


errorl 


@DosFreeSeg qw 
errorl 


@DosCloseQueue 
errorl 


q hdl 


@DosExit action,result 
ENDP 


ENDS 
END 


Figure 3.25b 


;free allocated segment 


7;close queue 


;Exit process 


(Concluded) 
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the 32-bit pointer to the allocated segment, back to the parent process via the queue. 
Also transferred with this call is the message length. Finally, the segment is set free 
for selector q_w. The queue is closed next and the child exits back to the OS/2. 


3.4.2 Shared Memory Segments 


In several cases among the preceding examples the processes involved employed 
shared memory segments. There were generally two types of mechanisms employed: 
giveable segments created using @DosAllocSeg or true shared segments created 
using @DosAllocShrSeg. Both of these approaches lead to a common sharing of a 
memory segment. These segments were used to transfer commonly needed informa- 
tion so that two independent (although possibly synchronized) processes could estab- 
lish a link. It is this need for some sort of common memory reference that charac- 
terizes all IPC, and shared memory is a very effective way to achieve this. 


3.5 SUMMARY 


In this chapter we have looked at memory management, multitasking, and inter- 
process communications. The goal has been to establish for the reader an introduc- 
tion to these techniques, with representative examples used to illustrate the mecha- 
nisms involved. A major attribute of OS/2 is the ability to access huge segments 
(greater than 64K). This was demonstrated in Section 3.2.4. 

Multitasking is a cornerstone of the operating system. As programming strate- 
gies change from the single-threaded way of doing business common throughout the 
1980s to more parallel approaches, OS/2 can be expected to move to the forefront 
of microcomputer operating systems. It must be recognized that multitasking requires 
a rethinking of how programs are structured in order to be able to take advantage of 
this feature. Programmers must begin to think in terms of how a given application 
can be subdivided so that the application can be run efficiently in a multitasked 
environment. This is a very nontrivial change in programming concept. Without the 
common availability of well-supported multitasking operating systems, it is, of 
course, impossible to begin the process of rethinking program structure to fit the 
multitasking mold. Hence OS/2 truly represents a transition in programming philoso- 
phy for the applications programmer. Fortunately, it has a great deal of commonal- 
ity with earlier systems such as DOS and the Windows executive, and consequently, 
represents a relatively fluid vehicle for many programmers to enter the world of 
multitasking. 

In Section 3.3 we discussed semaphores, multiple threads, and multiple proc- 
esses, all essential to a comprehensive multitasking environment. The semaphores 
treated consisted of two types: RAM and system (with a third being fast-RAM). In 
Section 3.4 we described the basic vehicles for interprocess communications, which 
had been alluded to earlier, and illustrated the use of pipes and queues. Shared 
memory segments were discussed throughout the chapter and signals were men- 
tioned briefly. 
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PROBLEMS 


3.1 IBM supplies a number of device drivers with the OS/2 libraries. They have extension 
SYS. The floppy and fixed disk driver for the IBM PC/AT is called DISKO1.SYS, 
and the driver for the inport Microsoft Mouse is MOUSEAO04.SYS, for example (see 
reference 5, p. 14). What level of protection would you expect these drivers to have? 
Why? 

3.2 Throughout this book the IBM (and Microsoft) macros have been used to access the 
API services. Typical of these is the call 


@DosExit action, result 


which executes the macro code 


@DosExit macro action, result 
@define DOSEXIT 
@pushw action 
@pushw result 
call far ptr DOSEXIT 
endm 


where @define and @pushw are defined as 


@define macro callname 
ifndef callname 
extrn callname:far 
endif 
endm 


and 
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@pushw macro parm 
Mov ax,parm 
push ax 
endm 


What are the advantages and disadvantages of this approach. Consider, for example, 
maintenance and clarity of code. 


3.3 When using @DosAllocSeg, what must occur for the segment to be created to be 
giveable? To be discardable? 


3.4 When accessing a huge segment, what is essential to achieving operation that ensures 
no violation of protection? 


3.5 What is the dominant feature of interprocess communications that must hold in any 
multitasking implementation? 


3.6 When would you be likely to use RAM semaphores for interprocess communications? 
To use system semaphores? 


3.7 In @DosWriteQueue why must the fourth macro parameter be pushed with @pushd 
not @pushs? Here 


@pushs Macro parm 
mov ax,SEG parm 
push ax 
lea ax,parm 
push ax 
endm 


while 


@pushd Macro parm 
push ds 
push bx 
mov ax, SEG parm 
mov bx,OFFSET parm 
push word ptr [bx] 
mov ax, [bx+2] 
push bp 
push sp 
pop bp 
xchg [bpt+6],ax 
pop bp 
mov ds,ax 
pop ax 
pop bx 
push ax 
endm 


3.8 When a child process, that is, using semaphores for interprocess communications, 
completes the execution of a critical area of code, how does it signal the parent? 
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a9 


3.10 
a 
cs 
J.Lo 
3.14 
bo 


3.16 
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Suppose that two processes involve no IPC and contain such code fragments as: 


Process 1 


@DosExecPgm... 
@errorl 


a 
@DosBeep freql,duration 


and 


Process 2 


OS21 PROC FAR 
’ 
@DosBeep freq2,duration 
@DosExit action,result 
OS21 ENDP 


What are the potential consequences of such code? 

What is the major difference between a pipe and a queue as used in this chapter? 
Compare the various IPC mechanisms. 

When would you use a shared segment as opposed to a giveable segment? 
Outline the API calls for pipe operation using a child process. 

Outline the API calls for queue operation using a child process. 


How is an intraprocess thread differentiated from an interprocess thread? What is 
preferred for a second task? 


Discuss the usage of DosAllocSeg and DosReAllocSeg in comparison to the use of 
DosSubAlloc. 


PART III 
Advanced O$/2 Kernal Programming 


40s/2andc 


There are a number of C compilers available; however, two that run under OS/2 
Protected Mode are the Microsoft C 5.1 Optimizing Compiler [1] and IBM’s C/2 
Version 1.1 [2]. In this book we use the former compiler. Together with the include 
files for the assembler (the .inc files), the IBM Toolkit [3] provides a set of C 
include files (.h files) that contain macros for accessing the Applications Program 
Interface (API) and Presentation Manager (PM) services. There are some significant 
difference’s between the Version 1.0 and 1.1 Toolkit files, particularly in the defi- 
nition of the structures used by API service calls. We will adhere to the Version 1.1 
definitions; the interested reader is referred elsewhere for the Version 1.0 definitions 
[4]. The purpose of this chapter is to introduce C programming in the Protected 
Mode context. 


4.1 HIGHER LEVELS OF ABSTRACTION 


C, by its very nature as a high-level language (HLL), is more abstract than assem- 
bler. This has distinct advantages when developing modular programs because the 
resulting code is more compact and easier to follow, assuming that the programmer 
has the language background. It does not necessarily facilitate optimum access to 
system hardware because the programmer must rely on the C compiler developer to 
provide these underlying service routines. In many cases, of course, these services 
are very optimized, but they must have some general-purpose features that could be 
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avoided if tailored assembler code were provided. This book assumes that the reader 
has a basic familiarity with the C language, as it did for assembler, and Appendix 
B reviews the C syntax in the Kernighan and Ritchie mold [5]. 

What do we mean by more abstract? Multiplication is an example. To square 
the variable x in C, one merely writes 


x = x * xX; 


To square the same variable in assembler (assuming that x is of word length), one 
has 


Mov ax, xX * load accumulator 

mov dx, 0 ; clear upper multiplicand 
mul x > multiply 

mov xX, ax ; reload x variable 


which is a bit more cumbersome. An even more exaggerated example is the line of 
C code 


y = (float) (sin(2.*PI*£*t) ); 


The conversion from double precision to floating point, alone, is a major system 
call, as is the reference to the sine mathematical function. These calls would encom- 
pass many lines of assembler code to accomplish the same algorithm. 

Hence abstraction can be a desirable feature as the programmer moves away 
from low-level system services and the hardware. Assuming that a programmer’s 
span of attention is limited to some rough measure of lines of code, the HLL allows 
a more efficient usage of this feature. 


4.1.1 The C Include Files 


The Toolkit has a number of include files used to set up the API calls and associ- 
ated variables, types, and structures used by these calls. The Toolkit is highly rec- 
ommended for users who quickly wish to begin programming OS/2 Protected Mode 
C, with its function-like interface. The major Toolkit include file is 


OS2.h 
which calls 


#include <OS2def.h> 
#include <bse.h> 


and requires a beginning program statement 
#define INCL_BASE 


Hence the first line of code prior to any API call would be 
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#define INCL_BASE 
#include <OS2.h> 


Note that OS2.h also has provisions to call pm.h, which loads the PM include 
routines. 
The file bse.h checks to see if INCL_BASE is set and then sets three symbols; 


INCL DOS 
INCL SUB 
INCL _DOSERRORS 


and (loads) 


#include <bsedos.h> /*Dos calls*/ 
#include <bsesub.h> /*Vio,Kbd,Mon calls*/ 
#include <bseerr.h> /*Error calls*/ 


where the first of these sets up the Dos prefix API calls. The second loads the Vio, 
Kbd, and Mon prefix API calls and bseerr.h loads the error calls. 

It is worthwhile pointing out a typical difference between the Version 1.0 
Toolkit and the Version 1.1. Consider the structure definition for getting the physi- 
cal buffer: 


Version 1.0 
struct PhysBufData { 
unsigned long buf start; /*start byte*/ 
unsigned long buf length; /*buffer length*/ 
unsigned selectors[2]; /*selector*/ 
}; 
Version 1.1 
typedef struct —_VIOPHYSBUF{ 
PBYTE pBuf; /*pointer to start byte*/ 
ULONG cb; /*buffer length*/ 
SEL asel[1]; /*selector*/ 
}VIOPHYSBUF; 


Clearly, to access these two structures, which serve the same purpose, requires 
radically different calling schemes. The programmer can expect to encounter this 
type of problem when converting Version 1.0 Protected Mode code to Version 1.1; 
however, it is generally desirable to use the Toolkit routines because of the abstrac- 
tion features intrinsic to these calls. 


4.1.2 The Low-Level Nature of the API 


We know that standard C code can be used for output to the display with calls of 
the type: 
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printf(“This is a display message.\n”); 


This can be accomplished with the standard I/O include file stdio.h and works in 
Protected Mode as well as Real Mode. To use the API call in equivalent fashion, we 
would need the more structured statements 


unsigned vio_hdl = 0; /*video handle*/ 
char *msg p = “This is a display message./n"; 
unsigned lmsg p = 0; 


lmsg _p = strlen(msg_p); 
VioWrtTTy((char far*)msg _p,lmsg_p,vio_hdl); 


Thus the reader can see that the API calls tend to be more cumbersome than stan- 
dard C code and more low level in nature. Clearly, as the example above high- 
lights, the programmer would want to use the standard I/O routines in this case. Fre- 
quently, however, services will be required in Protected Mode that cannot be accom- 
plished using the standard C functions. It is these activities that must access the API 
directly in low-level fashion. A very good example of this is the screen graphics 
modes, which require locking the screen and accessing the physical buffer all in 
conjunction with the mode set. These activities fit well with the notion of low-level 
calls in C. They correspond to low-level services: accessing the system resources 
directly. 

Generally, many of the API services are of this low-level nature. The reader is 
cautioned to use the standard C syntax where possible but recognize that the API 
services are designed to work in a multitasking environment and that some low-level 
interfacing will therefore always be necessary. 


4.1.3 Comparison of C with Assembler 


We have already seen several examples of the differences between C syntax and 
assembly language syntax when used to accomplish the same task. Typically, the 
assembler is much more detailed and incremental (each instruction accomplishes a 
much smaller piece of the overall task). As a further simplified example, consider 
addition in C: 


y = xl + x2; 
To accomplish this same syntax in assembler the following code is required: 


mov ax, X2 
add ax, xl 
MOV Y, ax 


Again, this assumes word integer arithmetic. If floating-point operations, for ex- 
ample, are to be implemented, the overhead increases dramatically. 
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Why, then, have we spent time learning the assembler interface in OS/2? A 
major reason is to understand the low-level nature of the API interface. In order to 
program the API from any language, the programmer must have a feeling for the 
syntax at a very basic level. Frequently, access is byte oriented and in order to get 
C code to function properly, the programmer must have this very basic understand- 
ing. The structures and parameter definitions for C calls to the API rely on a low- 
level interpretation, as found in the assembler calls. When problems arise in the C 
debugging process, assembler-level understanding of the API services provides 
invaluable insight into the C function calls. 


4.2 INTRODUCTORY C PROGRAMMING WITH OS/2 


Many application programs require a reasonable level of mathematical sophistication 
to achieve their intended computational goals. Generally speaking, assembly lan- 
guage is not the desired vehicle to achieve such sophistication. Modern languages 
have evolved such that a great deal can be accomplished within a single language 
to span the requirement of sophistication yet retain the ability to implement low- 
level services. The C language is such an implementation, and from this point on we 
shall concentrate on programming for OS/2 in the C context. Of course, we will 
make an occasional sojourn back to assembly language when the need arises. 


4.2.1 C Program Architecture and Structure 


Perhaps the easiest way to present the structure of a C program is with a simple 
example. Figure 4.1 contains a C program that prints the message 


Input word integer less than 32,768 


reads the input word integer value, and calls a function times_2(). The function 
times _2() has a single formal parameter that it doubles and converts from integer 
to floating point. Then the function prints the floating-point value of twice the ini- 
tial integer to the display with the message 


2 times the integer value = 


with the equal sign followed by the value. 
What is typical about this code? First, a comment line has been offset with the 
following form: 


f® sas */ 


Next, the C files needed by the program have been specified. In this program there 
is only one, stdio.h, and it is included with the statement 


#include <stdio.h> 
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/* A simple C program to illustrate Protected Mode I/O -- ioprgm.c */ 
#include <stdio.h> 
main() 

{ 


int x; /* input variable */ 


printf("Input word integer less than 32,768 \n"); 
scanf("%d", &x) ; 


times 2(x); /* function */ 


times 2(y) 
int y; /* formal parameter */ 


{ 
float z; /* floating point */ 


(float) (2.*y); /* double */ 


printf("2 times the integer value = %f\n",z); 


} 


Figure 4.1 The program ioprgm.c, illustrating typical program formatting for 
C code. 


Following this preprocessor area, the main function (called main()) appears and the 
code contained in this function is subtended within the curly brackets: {...}. The first 
line of code is a type declaration for x to be of type integer: int. Next the C stan- 
dard routine, printf(), is called, asking for the word integer input. The string con- 
tained in quotations is written to the display and terminated by the escape charac- 
ter, \n, which generates a carriage return and line feed. The scanf() routine is called 
to read an integer value (%d) into the location (using the address operator,&) speci- 
fied by x. Finally, the function times_2() is called with x passed as a parameter and 
main() is then ended. 

In the function times_2() the formal parameter, y, is declared to be of type 
integer and this is declared outside the body of the function. Within the body of the 
function all variables are locally defined. Here, for example, x is local to times_2() 
and is of type float (floating point). The value of y is doubled and converted to 
floating point with the cast: (float). This is used to define z. Next the value of z is 
output following the message. Note that the parameter specification (%f) corresponds 
to a floating-point output, while earlier we had (%d) to correspond to an integer 
format. 

Figure 4.2 illustrates the MAKE utility file used to compile and link the C 
code. In general the reader is referred to his or her compiler manual to understand 
the nature of this, but briefly the command 


cl -c -Zi -Os -FPc /Fcioprgm.cod ioprgm.c 


compiles the program (-c indicates do not link yet) and sets it up for the CodeView 
debugger (-Zi). The -Os parameter tends to reduce code size during optimization and 
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ioprgm.obj: ioprgm.c 
cl -c -Zi -Os -FPc /Fcioprgm.cod ioprgm.c 


ioprgm.exe: ioprgm.obj 
link /CO ioprgm.obj,ioprgm,ioprgm,slibce.1lib/NOE os2.1ib/NOE,, 


Figure 4.2. MAKE file for ioprgm.c. 


-FPc generates floating-point calls and selects the emulator math package. The state- 
ment 


/Fcioprgm.cod 


generates a mixed assembler and C code output file, and ioprgm.c indicates the C 
source file. 

The next set of lines in the MAKE file corresponds to the link operation. The 
/CO sets up CodeView. The first field contains the object modules(s); the second 
field contains ioprgm, where the default extension is .exe the run filename; and the 
third field contains ioprgm, the map filename with default .map. Next, the libraries 
are indicated, with the /NOE option that prevents multiple definitions of the same 
name. 

Figure 4.3 contains the list file for the mixed assembler and C source code 
(the .COD file). It is important to examine this file because it establishes the com- 
plexity of the C code in relation to the required assembly language instructions 
needed to represent each line of this C code. Note the large number of external 
routines called to implement the program appearing in Figure 4.1: __acrtused, 
_printf, scanf, chkstk,  fldw, fmnld,__fstsp,__flds, _fstdp, and __fltused. 
The text segment is TEXT and the data segment DAT. The data segment contains 
the strings of text and the integer formal specifier, %d. Aside from the initial setup 
for the routine _main, the print output asking for the integer less than 32,768 is 
accomplished with the assembly code following the designation for line 9. Next the 
integer is read in and a call made to times_2(). Finally, the main procedure ends. 
The times_2() code follows as a NEAR procedure with a number of calls to float- 
ing-point routines that emulate the coprocessor. These routines all begin with “f ”. 

The code in Figure 4.3 is instructive in that it illustrates the general techniques 
for generating assembly language instructions from C syntax. Note that no obvious 
Protected Mode calls were evident. These are all buried in the routines _ printf and 
_scanf. The basic C compiler template, however, is evident using TEXT, DATA, 
and DGROUP. 


4.2.2 Accessing the API from C 


The API is accessed in much the same fashion from C as it is from assembly lan- 
guage. Using the Toolkit definitions it is possible to set up the C function calls in 
a comfortable style for usage. Consider, for example, the prototyping for DosExit: 
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Static Name Aliases 


TITLE ioprgm.c 
NAME Loprgm 


. 8087 


_TEXT SEGMENT WORD PUBLIC ’ CODE’ 
_TEXT ENDS 
_DATA SEGMENT WORD PUBLIC ’ DATA’ 
_DATA ENDS 


CONST SEGMENT WORD PUBLIC ’ CONST’ 
CONST ENDS 
_BSS SEGMENT WORD PUBLIC ’ BSS’ 


BSS ENDS 
$$SYMBOLS SEGMENT BYTE PUBLIC ’DEBSYM’ 
$$SYMBOLS ENDS 


$$TYPES SEGMENT BYTE PUBLIC ’DEBTYP’ 
$$TYPES ENDS 
DGROUP GROUP CONST, _BSS, _DATA 
ASSUME CS: _TEXT, DS: DGROUP, SS: DGROUP 
EXTRN __acrtused: ABS 


EXTRN _printf: NEAR 
EXTRN _scanf:NEAR 


EXTRN __chkstk: NEAR 
EXTRN __fldw:NEAR 
EXTRN __fmuld: NEAR 
EXTRN __fstsp:NEAR 
EXTRN __flds: NEAR 
EXTRN __fstdp:NEAR 
EXTRN __fltused: NEAR 
_DATA SEGMENT 
$SG159 DB ’Input word integer less than 32,768 ’, OaH, OOH 
$SG160 DB ‘mea’, OOH 
$SG165 DB 72 times the integer value = %f’, OaH, OOH 
_DATA ENDS 
_TEXT SEGMENT 
ASSUME CS: _TEXT 


/* A simple C program to illustrate Protected Mode I/O -- ioprgm.c */ 
#include <stdio.h> 


main( ) 


PUBLIC -_main 
_main PROC NEAR 


kkk 000000 55 push bp 
kKk OOOOOL 8b ec mov bp,sp 
*kkK 000003 b8 02 O00 mov ax., 2 
kkk OOO0006 e8 00 OO call __chkstk 
x = -2 
OOK int x3 /* input variable */ 


printf("Input word integer less than 32,768 \n"); 


*xkx OO00009 b8 00 OO mov ax,OFFSET DGROUP: $SG159 
*kKkK OOODOOc 50 push ax 
xxx O00000d e8 00 O00 call “eri nve 
*kxk 000010 83 c4 02 add sp,2 
5 FokOKK scanf("%d" ,&x) ; 
; Line 10 
*xkxk 000013 8d 46 fe lea ax,WORD PTR [bp-2] 


*kk 000016 50 push ax 
kkk 000017 b8 26 00 mov ax,OFFSET DGROUP: $5G160 


Figure 4.3. The >COD file for ioprgm.c. 
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*kk OOO0O1a 50 push ax 
kkk OOOOLb e8 00 00 call _scanf 
x*kKxK OOO0O1e 83 c4 04 add sp,4 
5 KK 
5 | KKK times_2(x); /* function */ 
; Line 12 
*xkKx OOOO21 ff 76 fe push WORD PTR [bp-2] ;x 
kkk QO00024 e8 00 00 call _times_ 2 
*xkKxk 000027 83 c4 02 add sp,2 
5 | KKK } 
; Line 13 
kkk 00002a 8b e5 mov sp,bp 
*xkk OOOO2Zc 5d pop bp 
*xkxk 00002d c3 ret 
_main ENDP 
5 OK 
;,**Kk times 2(y) 
3 ok int y; /* formal parameter */ 
; Line 16 
_TEXT ENDS 
CONST SEGMENT 
$T20002 DQ 04000000000000000r ; 2.000000000000000 
CONST ENDS 
_ THERE SEGMENT 
ASSUME CS: _TEXT 
PUBLIC _times_2 
_times_2 PROC NEAR 
*kk O00002e 55 push bp 
KKK OOOO2F 8b ec mov bp,sp 
*xKx OOO0031 b8 04 O00 mov ax,4 
*Kxk 000034 e8 00 OO call __chkstk 
kkk 000037 56 push si 
5 kK { 
; Line 17 
; y=A4 
; 3 3 = 
5 | kK float 2; /* floating point */ 
» | kKK 
5 | OKK z= (flogt) (2. *y) 5 /* double */ 
; Line 20 
xkkx 000038 8d 5e 04 lea bx,WORD PTR [bp+4] 
i¥ 
kkk 00003b e8 00 O00 call __fldw 
KKK OO003e 8d le 00 O00 lea bx,WORD PTR $T20002 
*xkKxk 000042 e8 00 00 call __fmuld 
kkk 000045 8d 5e fc lea bx,WORD PTR [bp-4] 
72 
kkk 000048 e8 00 O00 call __fstsp 
5 1K 
5 | KKK printf("2 times the integer value = %f\n",z); 
; Line 22 
*kxk QOO0004b 8d 5e fc lea bx,WORD PTR [bp-4] 
;Z 
*xkx 00004e e8 00 00 call __flds 
*Kk OOOO51 83 ec 08 sub sp,8 
*xkxk 000054 8b dc mov bx,sp 
kkk QOO0056 e8 00 00 call __fstdp 
xxx 000059 b8 29 00 mov ax,OFFSET DGROUP: $SG165 
kkk GOOO5c 50 push ax 
kkk 00005d e8 00 00 call _printt 
*xkxk OOO06O 83 c4 Oa add sp,10 
5 kK 3}; Line 23 
xkk 000063 5e pop si 
kkk QOO0064 8b e5 mov sp,bp 
*kk 000066 5d pop bp 


Figure 4.3. (Continued) 
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KKK OOCO67 


times _2 ENDP 


_TEXT ENDS 
END 


Figure 4.3. (Concluded) 
VOID APIENTRY DosExit(USHORT,USHORT) 
Here the Toolkit definitions are 


#define VOID void 
#define APIENTRY pascal far 
Typedef unsigned int USHORT; 


The definitions have their usual meaning in C, and the only one needing an expla- 
nation is the type pascal. Pascal refers to the calling convention used in accessing 
the function DosExit. When a C function is called the formal parameters are loaded 
on the stack, starting with the last parameter first. In the pascal convention the last 
parameter is loaded last. In the assembler instruction set, the PUSH instruction puts 
its operand on the stack and decrements the stack pointer. Hence, the initiating 
assembly language code sequence (at the beginning of each function) 


push bp 
mov bp,sp 
sub sp,N 


causes the previous module’s (or calling module’s) base pointer, bp, to be saved on 
the stack and the current stack pointer value, sp, placed in bp. Prior to execution of 
this code, the calling program caused the called function (procedure) parameters to 
be placed on the stack along with a return address (invoked at the CALL) for the C 
convention. The called program places the parameters on the stack along with a 
return address for the pascal convention. The “sub sp,N” instruction above simply 
reserves N bytes of stack for local usage (N should be even). 

The API definitions include a large class of type definitions, such as PCHAR, 
for a pointer to a character where 


typedef CHAR FAR *PCHAR; 
Similarly, 
typedef ULONG FAR *PULONG 


defines a pointer to a LONG variable. 


Sec. 4.2 Introductory C Programming with OS/2 177 


A particularly important definition, is one that allows the programmer to estab- 
lish a FAR pointer: 


#define MAKEP(sel,off) ((PVOID)MAKEULONG(off,sel1) ) 
where 

typedef VOID FAR *PVOID; 
and 


#define MAKEULONG(1,h) ((ULONG)(((USHORT)(1)) | 
( (ULONG) ( (USHORT) ) (h) ) )<<16) ) 


Access of the video context, for example, is via the following sequence: 


VioSetMode (((struct_VIOMODEINFO far*)&CGAm),vio_hdl); 
VioScrLock (wait2, (char far *)dstatl,vio_hdl); 


VioScrUnLock(vio_hdl) ; 


Here the structure VIOMODEINFO is defined as CGAm and must satisfy the API 
constraints for structure members. It is defined in the Toolkit context as 


typedef struct _VIOMODEINFO { 

USHORT cb; 
UCHAR fbType; 
UCHAR color; 
USHORT col; 
USHORT row; 
USHORT hres; 
USHORT vres; 
UCHAR fmt_ID; 
UCHAR attrib; 
} VIOMODEINFO; 


Note that the structure above has the same form as the structure used in the assem- 
bly language programs except for the two added parameters, which are reserved and 
of no significance to the current programs. The video handle is short and declared 
with 


SHANDLE vio_hdl = 0; 
where 


typedef unsigned short SHANDLE; 
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The remaining parameters are defined as would be expected in the usual C conven- 
tion. 

This, then, is how the API access is achieved based on the Toolkit definitions. 
The programmer can, of course, choose to develop his or her own definitions; 
however, it can be expected that they would be similar to those found in the 
Toolkit. Note that the function prototyping follows the assembler conventions estab- 
lished in the API library by IBM. The parameter setup in these calls is similar to 
that established for the basic assembler routines except that a pascal convention has 
been used. 


4.2.3 Graphics Using C and OS/2 


Figure 4.4 illustrates the MAKE file for a program swave.c, which plots a dynami- 
cally varying sine wave. Figure 4.5a is the flowchart for swave.c and Figure 4.5b 
the actual program code for this module. This code opens with the needed include 
file accesses and then sets up the keyboard buffer, an associated structure, several 
integer and character parameters, and the floating point arrays x[] and y[]. Next the 
principal calling routine, the function main(), is established. 


swave.obj: 
cl -c -Zi -Os -FPc swave.c 


gphrout.obj: gphrout.c 
cl -c -Zi -Os -FPc gphrout.c 


swave.exe: swave.obj gphrout.obj 
link /CO swave.obj+gphrout.obj,swave,,Slibce.lib/NOE os2.lib/NOE 


Figure 4.4 MAKE file for swave.c. 


In the beginning of main(), a number of structures are defined: the physical 
buffer (PVBPrt2) and two video mode structures (CGAm and STDm). These all 
follow the convention of the Toolkit and the OS/2 parameter definitions for the API 
calls [6]. The sine wave is to be iteratively displayed: Each iteration is incremented 
a finite time interval to simulate motion. The total number of iterations read is 
followed by the setup for the video CGA mode. The first VioSetMode parameter 
could have been specified as 


(PVIOMODEINFO) &CGAm 


instead of using the structure-oriented syntax. The screen is locked and the physical 
buffer accessed, using VioGetPhysBuf(). Note that this access allows the program to 
return a selector to the buffer, PVBPrt2.asel[0]. The call to sine_wave() includes 
specification of the number of iterations and the selector to the physical buffer. Once 
the return from sine _wave() takes place, the screen is unlocked and a keyboard 
hesitate implemented. This is followed by a reset of the mode to 80 x 25 (STDm) 
and the program exit. 
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SETUP 
DATA 


INPUT # 
ITERATIONS 


SET CGA 


CLEAR 
SCREEN 


LOCK 
BUFFER 


GET PHYSICAL 
BUFFER SELECTOR 


PLOT 
SINE WAVE 


UNLOCK 
SCREEN BUFFER 


KEYBOARD 
HESITATE 


SET STD 
MODE 


EXIT 


Figure 4.5a Flowchart for swave.c. 


The sine_wave() program generates an array of 199 points of the sine wave of 
frequency 1 Hz and time interval of 0.02 second. This figure is plotted on the dis- 
play and then removed [with upltpt()]. After each plot followed by removal, the time 
value is incremented by one-tenth of a second. The routine cclsCGAQ() clears the 
CGA screen. Note that it functions similarly to the earlier main() calls to lock, 
unlock, and get the screen buffer. This routine calls clrCGA(), which actually writes 
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/* This routine sets & clears CGA mode with screen clear--swave.c 


* The generalized nomenclature is used. 


A dynamic sine wave has been added to the CGA mode output. 


This sine wave gradually moves across the screen 
The routine calls gphrout.c graphics functions. */ 


#define INCL_BASE 
#include <os2.h> 
#include <math.h> 


struct _STRINGINBUF lkbd_buf; 
CHAR kbd_buf[80]; 


UINT action = 0; 
UINT error_code = 0; 
UINT wait = 1; 


CHAR dstat[1]; 
CHAR dstati[1]; 


float x[250),y[250]; 


main() 
{ 
SHANDLE vio_hdl 0; 
SHANDLE kbd_hdl = 0; 
UINT wait2 = 1; 
UINT xb = 75,xe 
SEL MM1; 


150,yb = 25,ye = 175; 


int no_iter; 


struct _VIOPHYSBUF PVBPrt2; 
struct _VIOMODEINFO CGAm; 
struct _VIOMODEINFO STDm; 


PVBPrt2.pBuf = (BYTE far *) (0xB8000); 
PVBPrt2.cb = 0x4000; 


CGAm.cb = 12; 
CGAm.fbType = 7; 
CGAm.color = 2; 
CGAm.col = 40; 
CGAm.row = 25; 
CGAm. hres 320; 
CGAm.vres 


STDm.cb = 12 
STDm. fbType 
STDm.color 
STDm.col = 
STDm.row = 
STDm.hres 
STDm.vres 


lkbd_buf.cb = 80; 


printf("Input number of iterations\n") ; 
scanf("%d",&no_iter) ; 


Conditional load */ 


keyboard buf len */ 
keyboard buffer */ 


end thread */ 
result code */ 
reserved word */ 


lock status */ 
lock status */ 


screen coords */ 


video handle */ 
keyboard handle */ 
reserved */ 

box points */ 
selector */ 


number iteration */ 


physical buffer */ 
CGA structure */ 
80 x 25 struct */ 


buffer start */ 
buffer size */ 


struct length */ 
CGA mode */ 

CGA color */ 
text columns */ 
text rows */ 

CGA hor res */ 
CGA vert res */ 


struct length */ 
80 x 25 mode */ 
STD color */ 
text columns */ 
text rows */ 

STD hor res */ 
STD vert res */ 


buffer size */ 


no. updates */ 


/* set CGA mode */ 


VioSetMode(((struct _VIOMODEINFO far *) &CGAm) ,vio_hdl) ; 


cclsCGA(vio_hdl); 


VioScrLock(wait2, (char far *)dstat1,vio_hdl); 


/* clear CGA screen */ 


/* lock screen */ 
/* physical buffer */ 


Figure 4.5b The program swave.c, which plots a dynamic sine wave. 
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VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt2,vio_hdl); 


= PVBPrt2.asel[0]; 
sine_wave(no_iter,MM1) ; 
VioScrUnLock(vio_hdl) ; 


KbdStringIn((char far *)kbd_buf, 


/* selector */ 
/* sine wave */ 


7/* unlock screen */ 
/* hesitate screen */ 


((struct _STRINGINBUF far *) &lkbd_buf), 


wait,kbd hdl) ; 


/* set STD mode */ 


VioSetMode(((struct _VIOMODEINFO far *) &STDm) ,vio_hdl)j; 


DosExit (action,error_code) ; 


} 


sine_wave (NN, MM1) 
int NN; 
SEL MM1; 


{ 

float scale=35.,mid=100.; 

int mmid=100, zero=0, end=200,npts=199,n1,n; 
Gouble PI = 3.141592654,t; 


for(nl=1;nl <= NN;n1++) 

{ 

for(n=l;n <= npts;n++) 
{ 
y(n]=scale* (float) (sin(2.*PI*t) ) ; 
y(n]=mid-y[n]; 
x{n]=(int) (n) ; 
t = t +.02; 
} 


for(n=l;n <= (npts-1) ;n++) 
pltpt(x[n],x[n+1],y[n],y[n+1],MM1); 


for(n=l;n <= (npts-1) ;n++) 
upltpt(x[n],x[n+1],y[(n],y[(nt+1],MM1) ; 


} 


cclsCGA(vio_hdl1) 
SHANDLE vio_hdli; 
{ 
SEL MM; 
UINT waitl = 1; 
struct _VIOPHYSBUF PVBPrtl1; 


PVBPrt1.pBuf = (BYTE far *) (OxB8000) ; 
PVBPrtl.cb = 0x4000; 


VioScrLock(wait1, (char far *)dstat,vio_hdll); 


plot parameters */ 


start time */ 
loop screens */ 
loop array pts */ 
sine wave */ 
adjust plot */ 


col coordinate */ 
increment time */ 


plot points */ 


unplot points */ 


major shift */ 


/* physical buffer */ 


7* phys buf start */ 
7* buffer length */ 


/* lock screen */ 
/* physical buffer */ 


VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt1,vio_hdll) ; 


MM = PVBPrtl.asel[0]; 


C1rCGA (MM) ; 


Figure 4.5b (Continued) 


/* selector */ 


/* CGA clear */ 
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VioScrUnLock(vio_hdl1) ; unlock screen */ 


} 


c1lrCGA (MM) 
SEL MM; 
{ 
INT n; 
INT N1 = OX1F3F; end odd buffer */ 
INT DM = 0x2000; even offset */ 
PCHAR ptr; pointer scr buf */ 


for(n = O;n <= N1;n++) 


{ 
ptr = MAKEP(MM,n) ; odd far pointer */ 
eptr = 0; Clear odd buffer */ 


} 

for(n = O;n <= N1;n++) 
{ 
ptr = MAKEP(MM, DM+n) ; even far pointer */ 
eptr = 0; clear even buffer */ 
} 

} 


Figure 4.5b (Concluded) 


a zero to each byte in the CGA buffer area. The function MAKEPQ( is used to 
generate the pointer to the physical buffer values, with the selector value passed 
from the earlier VioGetPhysBuf() call and the offset generated internally. 

Figure 4.6 illustrates the graphics routines used in the calls to generate the sine 
wave graphics: wdot(), uwdot(), pltptQ, and upltptd. In addition, a box drawing 
routine bboxx() and the vertical and horizontal line drawing routines are included. 


4.2.4 Low-Level Access for Printer Graphics 


Figure 4.7 illustrates the MAKE file for a program, prtwave.c, which plots a sine 
wave on the graphics printer (in this case an Epson FX-85 dot matrix printer). The 
MAKE file specifies three C source code files: prtwave.c, the actual sine wave 
generator; pprtscr.c, a C source code file that contains the code to drive the printer; 
and gphrout.c, the graphics routines specified in Figure 4.6. 

Figure 4.8a illustrates the flowchart for prtwave.c and Figure 4.8b the corre- 
sponding source code for prtwave.c. This code is very similar to the program 
swave.c except that the printer routine arrays have been declared in the preproces- 
sor area and a new Sine wave routine, ssine_wave(), is called. This routine plots a 
single sine wave of 199 points at a selected frequency read in from main(). A call 
to prtscr() causes the screen to print on the printer. 

Figure 4.9a illustrates the flowchart for the print-screen CGA mode routine, 
pprtscr.c. Figure 4.9b contains the code for this routine. Note that this routine per- 
forms exactly like its counterpart, prtscr.asm, in assembly language. The only differ- 
ence is that an intermediate 16,000-byte buffer is not used. The same ESC charac- 
ter outputs are sent to the printer via DosWrite() once the printer is opened as a file 
device using DosOpen(). The data from the CGA screen is output as 25 blocks of 
640 bytes (eight rows by 80 bytes per row). The routine Idarray is used to load 


Al : 


Sec. 4.2 


Introductory C Programming with OS/2 


/* Graph routines Protected Mode--gphrout.c */ 


#define INCL BASE 
#include <os2.h> 


bboxx (xb, xe, yb, ye, MM1) 
UINT xb,xe,yb,ye? 
SEL MM1; 
{ 
lineh(yb,xb,xe,MM1) ; 
lineh(ye,xb,xe,MM1) ; 
linev(xb,yb,ye,MM1) ; 
linev (xe, yb, ye,MM1) ; 
} 

lineh(y,x1,x2,MM1) 
UINT y,xX1,xX2; 
SEL MM1; 
{ 
UINT n; 
for(n = xl;n <= x2;n++) 

wdot(n,y,MM1) ; 


} 
linev(x,y1,y2,MM1) 

UINT x,yl1,y2; 

SEL MM1; 

{ 

UINT n; 

for(n = yl;n <= y2;n++) 

wdot (x,n,MM1) ; 

} 
wdot (x,y,MM1) 

UINT x,y? 

SEL MM1; 

{ 

PCHAR ptr; 

UINT DM = 0x0000; 

CHAR MASK1 = 0x01; 


if(y & 0x01) 
DM = 0x2000; 


ptr = MAKEP(MM1,DM+(80*(y >> 1) + (x >> 2))); 
eptr =(*ptr | (MASK1 << (2*(3 - x % 4)))); 


} 
uwdot (x,y,MM1) 
UINT x,y? 
SEL MM1; 
{ 
PCHAR ptr; 
UINT DM = 0x0000; 
CHAR MASK1 = 0x00; 


if(y & 0x01) 
DM = 0x2000; 


ptr = MAKEP(MM1,DM+(80*(y >> 1) + (xX >> 2))); 


*ptr = (MASK1 << (2*(3 - x % 4))); 


} 
pltpt(x1,x2,y1,y2,MM1) 

float x1,x2,y1,y2; 
SEL MM1; 

{ 

float m; 

int row; 

int col; 


if(xl == x2) 
1000.; 


top line */ 
bottom line */ 
right line */ 
left line */ 


hor line */ 


vertical line */ 


x=col,y=row */ 


set dot */ 


even buffer */ 
dot location */ 
"OR" dot */ 


clear dot */ 


even buffer */ 
dot location */ 
write undot */ 


zero divide */ 


Figure 4.6 Graph routines used in the library cgraph.lib and taken from 


gphrout.c. 
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else 
(y2-y1) / (x2-x1) ; 7/* normal slope */ 
if( x2 > x1) 
{ 
for(col = (int) (x1)+1l;col <= (int) (x2) ;col++) 


row =(int) (yl + m*(col - x1)); /* line equation */ 
wdot(col,row,MM1) ; /* write dot */ 
} 
} 
else 
{ 
if (x2 < x1) 
{ 
for(col =(int) (x2)+1;col <= (int) (x1) ;col++) 
{ 
row=(int) (y2 + m*(col - x2)); 
wdot (col, row,MM1) ; /* write dot */ 
} 
} 


else 


{ 
col = (int) (x1); /* verticle line */ 
if(yl > y2) 
{ 
for (row=(int) (y2)+l;row <= (int) (yl) ;row++) 
wdot (col, row, MM1) ; 
} 


else 


for (row=(int) (yl)+l;row <= (int) (y2) ;row++) 
wdot (col, row,MM1) ; 
} 


} 


upltpt(x1,x2,y1,y2,MM1) 
float x1,x2,y1,y2; 
SEL MM1; 
{ 
float m; slope */ 
int row; 
int col; 


if(xl == x2) zero divide */ 
m = 1000.; 
else 
m= (y2-y1l)/(x2-x1); normal slope */ 
if(x2 > x1) 
{ 
for(col = (int) (x1) 7col <= (int) (x2) ;col++) 


row = (int) (yl + m*(col - x1)); line segment */ 
uwdot (col, row, MM1) ; erase dot */ 
} 

} 


else 


{ 
if(x2 < x1) 


{ 
for(col = (int) (x2)+1l;col <= (int) (x1) ;col++) 


row=(int) (y2 + m*(col -x2)); 
uwdot (col, row,MM1) ; /* erase dot */ 
} 

} 


else 


{ 
col = (int) (x1); 
st (Vi. > ¥2) 


for (row=(int) (y2)+l;row <= (int) (yl) ;row++) 
uwdot (col, row, MM1) ; /* erase dot */ 


) 


else 


for (row=(int) (y1)+l;row <= (int) (y2) ;rowt++) 
uwdot (col, row, MM1) ; /* erase dot */ 


184 Figure 4.6 (Concluded) 
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prtwave.obj: prtwave.c 
cl -c -Zi -Os -FPc prtwave.c 


pprtscr,.obj: pprtscr.c 
cl -c -Zi -Os -FPc pprtscr.c 


\ gphrout.obj: gphrout.c 
cl -c -Zi -Os -FPc gphrout.c 


prtwave.exe: prtwave.obj pprtscr.obj gphrout.obj 
link /CO prtwave.obj+pprtscr.obj+gphrout.obj,prtwave,,\ 
slibce.1lib/NOE os2.1lib/NOE, 


SETUP 
DATA 


Figure 4.7 MAKE file for prtwave.c, which plots a sine wave on the printer. INPUT 
FREQUENCY 


SET CGA 
MODE 


CLEAR 
SCREEN 


LOCK 
BUFFER 


GET PHYSICAL 
BUFFER SELECTOR 


PLOT 
SINE WAVE 


PRINT 
SCREEN 


UNLOCK 
SCREEN BUFFER 


KEYBOARD 
HESITATE 


SET STD 
MODE 


Figure 4.8a Flowchart for a program 
prtwave.c, which plots a sine wave on 
the printer. 


EXIT 
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This routine sets & clears CGA mode with screen clear--prtwave.c 
The generalized nomenclature is used. 

A sine wave has been added to the CGA mode output. 

The routine calls gphrout.c graphics functions. 

It prints the plot. */ 


#define INCL_BASE 
#include <os2.h> 
#include <math.h> 


Conditional load */ 


struct _STRINGINBUF lkbd_buf; 
CHAR kbd_buf[80]; 


keyboard buf len */ 
keyboard buffer */ 


UINT action = 0; end thread */ 
UINT error_code 0; result code */ 


UINT wait = 1; 


CHAR dstat[1]; 
CHAR dstat1[1]; 


float x[250],y[250]; 


reserved word */ 


lock status */ 
lock status */ 


screen coords */ 


BYTE col1[320]; column array */ 
BYTE MM[4] = {0x40,0x10,0x04,0x01}; mask */ 

BYTE w[8] = (128,64,32,16,8,4,2,1); weights */ 

BYTE s[4]? dummy */ 

BYTE shiftl1[4] = (6,4,2,0}; shift count */ 
BYTE in_buffer1[4] {Ox1B,0x4B,64,1); ESC K (320-256) */ 
BYTE in_buffer2[2] {Ox0D, Ox0A); CR,LF */ 

BYTE in_buffer3[3] {Ox1B,0x41,8}; ESC A 8/72 */ 

BYTE in_buffer4[2] {Ox1B,0x32}; ESC 2 */ 

BYTE dev_name[5] = {'L','P','T','1',0}; device */ 


main() 


{ 


extern prtscr(); PrtSc routine */ 


SHANDLE vio_hdl ; video handle */ 


SHANDLE kbd_hdl 
UINT wait2 = 1; 


UINT xb = 75,xe 150,yb = 25,ye 


SEL MM1; 


float freq; 


keyboard handle */ 
reserved */ 

box points */ 
selector */ 


frequency */ 


struct _VIOPHYSBUF PVBPrt2; 
struct _VIOMODEINFO CGAm; 
struct _VIOMODEINFO STDm; 


physical buffer */ 
CGA structure */ 
80 x 25 struct */ 


PVBPrt2.pBuf = (BYTE far *) (OxB8000) ; buffer start */ 


PVBPrt2.cb = 0x4000; 


CGAm.cb = 12; 
CGAm.fbType = 7; 
CGAm.color = 2; 
CGAm.col = 

CGAm. row 
CGAm.hres = 320; 
CGAm.vres = 200; 


STDm.cb = 12; 
STDm.fbType = 1; 
STDm.color = 4; 
STDm.col = 80; 
STDm.row = 25; 
STDm. hres 720; 
STDm.vres 400; 


Figure 4.8b The program prtwave.c. 


buffer size */ 


struct length */ 
CGA mode */ 

CGA color */ 
text columns */ 
text rows */ 

CGA hor res */ 


CGA vert res */ 


struct length */ 
80 x 25 mode */ 
STD color */ 
text columns */ 
text rows */ 

STD hor res */ 
STD vert res */ 
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lkbd_buf.cb = 80; /* buffer size */ 


printf("Input frequency (Hz) \n"); 
scanf ("%f", &freq) ; 


/* set CGA mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &CGAm) ,vio_hdl); 


cclsCGA(vio_hdl) ; /* clear CGA screen */ 
VioScrLock(wait2, (char far *)dstat1,vio_hdl); /* lock screen */ 


/* physical buffer */ 
VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt2,vio_hdl) ; 


MM1 = PVBPrt2.asel[0]; /* selector */ 
ssine_wave(freq,MM1) ; /* sine wave */ 
prtscr(MM1) ; /* print screen */ 
VioScrUnLock(vio_hdl); /* unlock screen */ 


/* hesitate screen */ 
KbdStringiIn((char far *)kbd_buf, 
((struct _STRINGINBUF far *)&lkbd_buf), 
wait,kbd_hdl) ; 
/* set STD mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &STDm) ,vio_hdl); 


DosExit(action,error_code) ; 


} 


ssine_wave(freq,MM1) 


float freq; 

SEL MM1; 

{ 

float scale=35.,mid=100.; /* plot parameters */ 
int mmid=100, zero=0,end=200,npts=199,n1,n; 

double PI = 3.141592654,t; 


t = 0.0; /* start time */ 
for(n=1;n <= npts;n++) /* loop array pts */ 
{ 
y(n]=scale* (float) (sin(2.*PI*freq*t) ) ; /* sine wave */ 
y(n)=mid-y[n]; /* adjust plot */ 
x(n)=(int) (n) ; /* col coordinate */ 
t = t +.02; /* increment time */ 


} 
for(n=1l;n <= (npts-1) ;n++) 
pltpt(x[{n],x[{nt+1],y[(n],y[n+1],MM1); /* plot points */ 


} 


cclsCGA(vio_hdl1) 


SHANDLE vio_hdll; 
{ 


SEL MM2; 

UINT waitl = 1; 

struct _VIOPHYSBUF PVBPrt1; /* physical buffer */ 
PVBPrt1.pBuf = (BYTE far *) (OxB8000) ; /* phys buf start */ 
PVBPrtl.cb = 0x4000; /* buffer length */ 
VioScrLock(wait1, (char far *)dstat,vio_hdll); /* lock screen */ 


/* physical buffer */ 
VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt1,vio_hdll); 


MM2 = PVBPrtl.asel[0]; /* selector */ 


Figure 4.8b (Continued) 
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C1rCGA (MM2) ; CGA clear */ 


VioScrUnLock(vio_hdl1) ; unlock screen */ 


c1rCGA (MM3) 
SEL MM3; 
{ 
INT n; 
INT N1 = Ox1F3F; end odd buffer */ 
INT DM = 0x2000; even offset */ 
PCHAR ptr; pointer scr buf */ 


for(n = O;n <= N1;n+t) 


ptr = MAKEP(MM3,n); odd far pointer */ 
*eptr = 0; clear odd buffer */ 


for(n = O;n <= Nl1;n++) 
{ 
ptr = MAKEP(MM3,DM+n) ; even far pointer */ 
eptr = 0; clear even buffer */ 
} 

} 


Figure 4.8b (Concluded) 


these eight rows in the following manner: For each of the 80 bytes in a row, the 
byte is unfolded into its four pixel values (to make the 320 pixels per CGA row). 
The single byte containing the four pixel values is stored in four locations: s[O], s[1], 
s[2], and s[3]. These values are in turn masked, shifted, and weighted according to 
their row position. A running total is generated across all rows for each pixel posi- 
tion and stored in coll[]. The col1[] values are returned to prtscr() (the pprtscr.c 
function that accomplishes the screen print). Each buffer row and column value is 
returned using 


prt = MAKEP (MMl, DM + (80 *(row>>1) + (col>>2))); 


Here MM1 is the selector value and DM = 0x2000 if the row value is odd. Figure 
4.10 illustrates a typical sine wave plotted using this program. 


4.3 MEMORY MANAGEMENT AND MULTITASKING WITH C 


The API services offer a wide variety of multitasking and memory management 
options, as we have seen. There is an important constraint to consider when employ- 
ing programs that run in a multitasking environment: The code is reentrant if differ- 
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OPEN 
PRINTER 
SET 
SPACING 
SET 
LINES 
SETUP BLOCK AND 
BLOCK COUNT 
CALL 
| darray ( ) 
SET 
GRAPHIC MODE 
PRINT 
COLUMNS 
OUTPUT 
CR&LF 
INCREMENT 
BLOCK 


Figure 4.9a Flowchart for the 


program pprtscr.c, which performs 
PRINTER the print operation in CGA mode. 
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/* This is a C print screen routine -- pprtscr.c 


#define INCL_BASE 
#include <os2.h> 


prtscr (MM1) 
/* selector */ 


extern in_bufferl /* ESC K (320-256) r */ 

extern in_buffer2 /* CR,LF */ 

extern in_buffer3 /* ESC A 8/72 */ 

extern in_buffer4 /* ESC 32 -- 1/6 */ 
/* byte counts */ 

USHORT bytesin=320,bytesout=0,bytesin1=4,bytesin2=2,bytesin3=3; 


extern BYTE dev_name[]; /* device name */ 
HFILE dev_hand 0; /* handle */ 

USHORT dev_act 0; action */ 

ULONG dev_size 0; size */ 

USHORT dev_attr = 0; attribute */ 
USHORT dev_flag 1; open file */ 
USHORT dev_mode = 0x00C1; private,nodeny */ 
ULONG dev_rsv = 0; reserved */ 


extern BYTE coll[]; column array */ 


UINT N; block count */ 
int blk_cnt,sixforty=640,n; 


/* open printer */ 
DosOpen (dev_name, (PHFILE) &dev_hand, (PUSHORT) &dev_act,dev_size, 
dev_attr,dev_flag,dev_mode,dev_rsv) ; 
/* set spacing */ 
DosWrite(dev_hand,in_buffer3,bytesin3, (PUSHORT) &bytesout) ; 
/* set lines */ 
DosWrite(dev_hand,in_buffer4,bytesin2, (PUSHORT) &bytesout) ; 


b1lk_cnt=0; /* 640 block */ 
for(n=1l;n <= 25;n++) 

{ 

N = blk_cnt * sixforty; /* block bytes */ 


ldarray(N,MM1) ; /* load array */ 

/* graphics mode */ 
DosWrite(dev_hand,in_bufferl,bytesin1, (PUSHORT) &bytesout) ; 

/* print columns */ 
DosWrite(dev_hand,coll,bytesin, (PUSHORT) &bytesout) ; 

/* CR,LF */ 
DosWrite(dev_hand,in_buffer2,bytesin2, (PUSHORT) &bytesout) ; 


blk_cnt++; /* inc block count */ 
} 
DosClose (dev_hand) ; /* close printer */ 


} 


ldarray (N,MM1) 
UINT N; 
SEL MM1; 
{ 
extern BYTE ; mask */ 
extern BYTE weights */ 
extern BYTE dummy */ 
extern BYTE i ; shift */ 


Figure 4.9b The routine pprtscr.c. 
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int n,n1,m,N4,row,col; 
extern BYTE colli[]; 


N4 
for 


} 
rbuf(y,x,MM 
SEL MM1; 


int 


{ 


= N/80; 


(n = O;n <= 


for(m = O;m 


79 ;n++) 


<= 3;m++) 


coll[(n*4+m] = 0; 
for(nl = O;nl <= 7;n1++) 


row = N4 


+ nl; 


for(m = O;m <= 3;mt+) 


{ 
col = 
s[m] 
} 
for(m = 
{ 
s[m] 
s[m] 
s[m] 
col = 


coll[col] = coll[col] + s[m]; 


} 
} 
1) 


x,Yi 


PCHAR ptr; 
UINT DM = 0x0000; 


if(y & 0x01) 


ptr 


DM = 0x2000; 


= MAKEP(MM1,DM + (80*(y >> 1)+(xX >> 2))); 


return (*ptr) ; 


} 


n*4; 


= rbuf(row,col,MM1) ; 


?m <= 3;m++) 


(s({m] & MM[m]); 


(s{m] >> shiftl[m]); 


s{m] * w[nl]; 
n*4 + m; 


Figure 4.9b (Concluded) 


column array */ 


block row */ 


initialize */ 


nearest byte */ 
screen byte */ 


mask */ 

shift rt */ 
weight */ 
column index */ 
column value */ 


selector */ 
X=col,y=row */ 


buffer ptr */ 
even/odd */ 
odd row */ 


byte pointer */ 
return value */ 
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Figure 4.10 Representative sine wave 
output for the program prtwave.c. 
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ent threads call the same function. Hence in multithreaded applications the API 
services, which have code written for the multithreaded environment, are a more 
desirable way to write code than are the multithreaded versions of the standard C 
library routines. We always base our routines on the API calls. 

In general, the variety of memory management services is large. These serv- 
ices include DosAllocSeg(), DosSubAllocSeg(), and DosAllocShrSeg(). In the next 
section we consider the creation of a shared segment. This is among the more 
complex variants of segment manipulation and constitutes a useful example. Simi- 
larly, the creation of a process or thread can be contingent on synchronization. For 
example, if both a parent and a child process access a shared segment, some form 
of synchronization is needed to ensure that one process does not write over the 
results of another before the data is properly used. In general we achieve synchro- 
nization using semaphores. This approach, using semaphores for synchronization and 
the API services for multitasking, allows easy development of both non-reentrant 
and reentrant code in the OS/2 multitasking environment. Memory management is, 
of course, a subset of this activity, particularly when sharing segments. 


4.3.1 Creating and Accessing Segments 


A good example of the use of memory management is the creation and access of 
shared segments. Figure 4.11a is a flowchart for the program pipestc.c. This program 
is the C version of the assembly language program, pipest.asm, which appears in 
Figure 3.22b. The program sets up a shared segment, creates a pipe, uses sema- 
phores for synchronization, and passes a message to the pipe via the pipe’s buffer 
area. A child process, pipeclc.c, then reads the pipe message and prints the message 
to the screen. The process is shown in Figure 4.11b, and the code for the child 
process appears in Figure 4.12. The MAKE file for pipestc.c is illustrated in Figure 
4.13a, and the MAKE file for pipeclc.c is presented in Figure 4.13b. 

The program pipestc.c opens with four string expressions of CHAR type. 
These expressions define the pointers msg pd, prgm_nm, shrname, and asem1. 
Within the calling function, main(), a number of local variables have been defined 
using the standard OS/2 type casts. In the API service call to DosAllocShrSeg(), for 
example, the parameters are of the type 


SEL msell; 
CHAR FAR *shrname; 
USHORT msize = 512; 


where USHORT = unsigned short (16-bit word) and SEL denotes a selector: un- 
signed short SEL. The actual call in DosAllocShrSeg() specifies that the selector, 
msell, be specified as a pointer object: 


(PSEL) &msell 


Here the address of msell is treated as the pointer, as it should be. 
When DosMakePipe() executes a read handle and write handle are returned for 
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PIPE 


PASS PIPE READ 
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CREATE 
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4 


SET 
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SEMAPHORE 


KILL 
PROCESS 


Figure 4.1la Flowchart for C program 
to emulate pipest.asm, a pipe and 


EXIT 
shared segment program. 
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/* Program to emulate pipest.asm -- pipestc.c 
* This routine sets up a child and accesses a shared 
* memory segment. */ 


#define INCL_BASE 
#include <os2.h> 
#include <string.h> 


"This is the OS/2 pipe message\n"; 

"PTPECLC. EXE"; 

"\ \SHAREMEM\\SDAT1. DAT"; 

FAR *aseml "\\SEM\\SDAT. DAT"; 
blank[1] {0x0007}; Scroll attribute */ 
lmsg_p0; length result */ 


*msg po 
FAR *prgm_nm 
FAR *shrname 


Shared buffer */ 
USHORT Buffer size */ 
SEL msell; Selector */ 


Pipe parameters */ 
HFILE read_hdl,write_hdl; Pointer to pipe handles */ 
USHORT pflag = 256; Pipe size bytes */ 
USHORT bytes written; Length of write */ 


Semaphore parameters */ 
USHORT no_excl = 1; No exclusive */ 
HSEM sem_hdll; Semaphore handle */ 
LONG no_to = -1; No timeout */ 


Beep */ 
USHORT freq = 5000; 5,000 Hertz */ 
USHORT duration = 500; 500 millisec */ 


Child process */ 
CHAR obj_nm_buf[40]; Failure buffer */ 
USHORT lobj_nm_buf = 40; Length buffer */ 
USHORT async Child asynchronous */ 
CHAR argst = NULL command parm */ 
CHAR envst = 0; NULL environment parm */ 
RESULTCODES PIDD; Structure-result codes */ 


PUINT ptr; Pointer */ 


USHORT action = 1; Terminate all threads */ 
USHORT result ; Completion code */ 


USHORT error2; Dummy error return */ 


Clear screen */ 


/* Create shared segment */ 
error2 = DosAllocShrSeg(msize,shrname, (PSEL) &msel1) ; 


/* Check creation error */ 
if(error2 != 0) 


printf("Result code = %¢d",error2) ; 
exit(1); 
} 


Figure 4.11b Program code for pipestc.c, illustrated in Figure 4.11a. 
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Create pipe */ 


DosMakePipe( (PHFILE) &read_hdl, (PHFILE) &write_hdl,pflag) ; 


ptr = 
*eptr = 


MAKEP(msell1,2) ; 
read_hdl; 


/* 
/* 


/* 


Pointer to 2nd word */ 
Read handle */ 


Create system sem */ 


DosCreateSem(no_excl, (PHSEM) &Sem_hd11, (PCHAR) asem1) ; 


DosBeep (freq, duration) ; /* 
/* 


/* 
DosWrite(write_hdl, (PVOID)msg_p0,lmsg_po, 


lmsg_pO = strlen(msg_p0); 


Beep speaker */ 
Length of message */ 


Write to handle */ 


(PUSHORT) &bytes written) ; 


ptr = 
*ptr = 


MAKEP(msel1,4) ; 
bytes_written; 


/* 
/* 


/* 


/* 
DosExecPgm((PCHAR)obj_nm_buf, 
lobj_nm_buf,async, 
(PCHAR) &argst, 
(PCHAR) &envst, 
(PRESULTCODES) &PIDD, 
prgm_nm) ; 


DosSemSet (sem_hdl1) ; 


error2 = 


/* 
if(error2 != 0) 
printf("Error on opening child"); 
exit(1); 
} 
DosSemWait(sem_hdl1,no_to) ; 


/* 
/*® 


Pointer to 3rd word */ 
Length of write */ 


Set semaphore */ 


Initiate child */ 


Check creation error */ 


Wait on child */ 


Terminate child */ 


DosKillProcess (PIDD.codeTerminate, PIDD.codeResult) ; 


DosExit(action,result) ; 


} 


/* 


{ 
USHORT 
USHORT 
USHORT 
USHORT 
USHORT 
HVIO 


oo 


“Ib 
lO W se we 


Terminate parent */ 


top row */ 

left column */ 
bottom row */ 
right column */ 
no. lines */ 
handle */ 


Clear screen */ 


VioScrollUp(tr,lc,br,rc,no_line, (PCHAR) blank,vio_hdl) ; 


} 


Figure 4.11b (Concluded) 


the pipe. The read handle, read_hdl, is written into the second word of the shared 
segment. A semaphore is created to synchronize the parent and child process. Essen- 
tially, we want the parent to wait on the child process until the child completes its 
write to the screen. The parent process (pipestc.c) writes the message to the pipe 
buffer using DosWrite(), and a return count of the length of the message written is 


placed in the shared segment buffer at offset 4. Next, 


the semaphore is set and the 


child process started. Once the child completes, the semaphore is cleared and the 
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/* This is the child process -- pipeclc.c 
* It writes the actual screen message using pipes */ 


#define INCL_BASE 
#include <os2.h> 


CHAR FAR *aseml = "\\SEM\\SDAT. DAT"; 

CHAR FAR *shrname "\ \SHAREMEM\\SDAT1. DAT"; 
CHAR buffer[256]; 

main() 

/* 

* 


* 


USHORT action 
USHORT result 


HVIO vio_hdl; 
USHORT freq = 4000; 
USHORT duration = 500; 
HSEM sem_hdll1; 

SEL shrsel; 

HFILE read_hdl; 


USHORT 
USHORT _read; 


USHORT 


DosOpenSem((PHSEM) &sem_hd1ll1,asem1) ; 
DosBeep (freq, duration) ; 
DosGetShrSeg (shrname, (PSEL) &shrsel) ; 
ptr = MAKEP(shrsel,2); 

read_hdl = *ptr; 


ptr = MAKEP(shrsel,4) ; 
lmsg = *ptr; 
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Exit parameters */ 
Terminates all threads */ 
Completion code */ 

Video handle */ 

Beep */ 

4,000 Hertz */ 

500 millisec */ 

Semaphore handle */ 
Shared Segment Sel */ 
Read handle */ 


Length message */ 
Bytes read */ 


32-bit pointer */ 


Open semaphore */ 


Beep speaker */ 
Shared Segment */ 


Pointer to 2nd word */ 
Read handle */ 

Pointer to 3rd word */ 
Length of message */ 


/* Read message */ 


DosRead (read_hdl,buffer,1msg, (PSHORT) &bytes_ read) ; 


VioWrtTTy (buffer,1lmsg,vio_hdl) ; 
DosSemClear(sem_hdl1) ; 


DosExit(action,result) ; 
) 


/* Write message */ 
/* Clear semaphore */ 


/* Terminate process */ 


Figure 4.12 Program code for child process, pipeclc.c, used by pipestc.c. 
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pipestc.obj: pipestc.c 
cl -c -Zi -Os -FPc pipestc.c 


pipestc.exe: pipestc.obj 
link /CO pipestc.obj,pipestc,,\ 
slibce.lib/NOE os2.1ib/NOE,, 


pipeclc.obj: pipeclc.c 
cl -c -Zi -Os -FPc pipeclc.c 


pipeclc.exe: pipeclc.obj 
link /CO pipeclc.obj,pipeclic,,\ 
slibce.lib/NOE os2.1ib/NOE,, 


(b) 


Figure 4.13 (a) MAKE file for pipestc.c and (b) MAKE file for pipeclc.c. 


wait state for the parent is terminated. The child process is terminated (along with 
any dependent processes), and the parent is completed with the termination 
DosExit(). The child process is illustrated in Figure 4.12. 


4.3.2 Creating a Thread or Process 


In Figure 4.11b the parent process initiates a child process specified using the 
pointer prgm_nm. This specification links the two processes and is the last parame- 
ter of DosExecPgm(). Figure 4.12 contains the program for the child. Note that the 
semaphore name and the shared segment name are the same as those specified by 
the parent. This constitutes the common link between the two processes. The speaker 
is beeped to indicate that the child is operating. The shared segment is retrieved and 
the pipe read handle and buffer length obtained. DosRead() is used to load buffer[] 
with the message in the pipe, and this message is printed using VioWvtTTY(. 

The return to the parent results in termination of the work semaphore. The 
child process is terminated by the parent, as well, with a full exit from the parent 
mode. Note that DosKillProcess() is not absolutely necessary because the child, 
pipeclc.exe, has been terminated but is good programming practice because it termi- 
nates all dependent processes started by the child, in addition to the child process 
itself, if needed. Figure 4.11b also illustrates the clear screen routine, which is a one- 
time call to VioScrollUp(). 

Figure 4.14 contains the MAKE file for a program ckthread.c, which creates a 
thread as opposed to a new process. Remember that a thread shares resources with 
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ckthred.obj: ckthred.c 
cl -c -Zi -Gs -FPc -F COO -Lp ckthred.c 


ckthred.exe: ckthred.obj 
link /CO ckthred.obj,ckthred,ckthred,slibce.lib/NOE os2.1lib/NOE,, 


Figure 4.14 MAKE file for ckthred.c. This program checks the formation of 
child threads. 


the subordinate or child threads. This is unlike creation of a new process, where 
each subordinate process has its own encapsulated resources. 

Since each thread has its own stack (a resource unique to the thread) a high- 
level-language compiler such as C will report stack overflow errors because the 
thread’s unique stack space does not overlap within a given process. This usually 
generates an error message (in the Microsoft C Optimizing Compiler Version 5.1, 
for example). To avoid such error messages, a compiler option, -Gs, can be used to 
eliminate stack checking only when the stack space is known to be sufficient [7]. 
This will allow the compilation of programs that generate separate threads without 
generating an error condition. Each thread should allow a minimum stack size of 
2048 bytes. In Figure 4.14 the compile and link allow generation of symbolic 
debugging information through options -Zi (compiler) and /CO (linker). 

Figure 4.15 illustrates a simple OS/2 C language program which generates a 
thread that prints the message 


“This is the subordinate thread” 


to the display. A second message is printed following completion of the child thread 
action and return to the parent calling thread. The latter thread prints the message 


“This is the main thread” 


Both threads generate 500-millisecond tones. Synchronization is achieved using 
semaphores. 

In the example program illustrated in Figure 4.15, no error checking exists 
following the API calls. This is because the program is fully debugged and the need 
for such diagnostics is minimized. During the debugging phase such diagnostics 
were included. Should a malfunction occur the user can, of course, set up such 
checking procedures. Note that in the call DosCreateThread(), the third parameter 
references byte 2047 in the stack as the stack start. This is because of the way the 
stack pointer is changed following a push to the stack. Element 2047 is the top of 
the stack in terms of address, and each push decrements the stack pointer to a lower 
address. Throughout this example the Toolkit nomenclature has been used. The type 
casting is in keeping with the Toolkit defined types and the actual API calls reflect 
the IBM Toolkit definitions for setup of the API functions. 
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#define INCL_BASE 
#include <os2.h> 


#include <string.h> 
#define SSIZE 2048 


void FAR thread1(void) ; 


CHAR *msg_pl "\n This is the main thread \n"; 

CHAR *msg_p2 "This is the subordinate thread \n"; 

CHAR FAR *aseml = "\\SEM\\SDAT. DAT"; 

CHAR stack1[SSIZE]; 7/* Stack for threadl */ 
HVIO vio_hdl; 

HSEM sem_hdll; 


size_t lmsg_pl; 
size_t lmsg_p2; 


main() 
{ 
USHORT freq = 3000, duration = 500; 
USHORT action = 1, result = 0, no_excl = 1; 


TID threadID; /* Thread ID */ 
LONG no_to = -1; /* no timeout */ 


DosBeep (freq, duration) ; /* Beep Speaker */ 

/* Create semaphore */ 
DosCreateSem(no_excl, (PHSEM) &Sem_hd11, (PCHAR) asem1) ; 
DosSemSet (sem_hdll) ; /* Set semaphore */ 
DosCreateThread (thread1, (PTID) &threadID, (PBYTE) &Stack1[2047]) ; 
DosSemWait(sem_hdl1,no_to) ; /* Wait thread */ 
lmsg_pl = strlen(msg_p1); /* Length Message 1 */ 
VioWrtTTy (msg_p1,1lmsg_p1,vio_hdl); 


DosExit (action,result) ; End main thread */ 


} 


void FAR thread1(void) 


{ 
USHORT freqli = 5000, duration = 400; 


DosBeep(freqi,duration) ; Beep speaker */ 
lmsg_p2 = strlen(msg_p2) ; Length Message 2 */ 
VioWrtTTy (msg_p2,1lmsg_p2,vio_hdl); Message 2 */ 


DosSemClear(sem_hdll) ; Clear semaphore */ 


} 


Figure 4.15 The program ckthred.c, which creates and exercises a child thread. 
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4.4 OTHER PROGRAMS 


We have seen several examples of how to employ the API services in the C envi- 
ronment. These were beginning examples. In this section it will be useful to develop 
several more examples illustrating the lower-level nature of the API calls in this C 
environment. A great deal about the OS/2 implementation can be learned from these 


examples since frequently implementation features are obscured by the general 
syntax considerations. 


4.4.1 A Rotating Tetrahedron 


As a Starting point, consider two-dimensional space represented by the usual Carte- 
sian axes: x and y. Now consider the rotation of the point (x,, y,) to (,, y,). Here, 
if r is the radius of the points from the origin 


x, = rcos(a,) (4.1) 
y, = rsin@,) (4.2) 
and 
x, = r cos(a,) (4.3) 
y, = rsin(a,) (4.4) 
Writing 
a1 = a+a, (4.5) 
we have 
Xx, r cos(a + a.) 
= (4.6) 
Y, r sin(a + a) 
which becomes 
xX, xX, cos(a) — y, sin(a) 
= (4.7) 
¥,, x, sin(a) + y, cos(a) 


when the trigonometric identities are used for sine and cosine of the addition of two 
angles [4]. In matrix form 


Xi x, cos(a) — sin(a) x. 
= (4.8) 
ys y, sin(a) + cos(a) y, 


This rotation can be extended to three dimensions, where 
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a : rotation angle about the x-axis 
8B : rotation angle about the y-axis 
y : rotation angle about the z-axis 


and we obtain the rotation matrices (A, B, and C, respectively) appearing in Table 
4.1. Choosing an order to the rotation, we generate an overall three-dimensional 
rotation given by the matrix 


R=CBA (4.9) 


This matrix is indicated in Table 4.1 and will serve as the basis for rotation of the 
tetrahedron. Note that the three rotations in Equation (4.9) are not orthogonal. We 
would need to select a different set of rotation angles to ensure orthogonality. 


TABLE 4.1 ROTATION MATRICES FOR THREE-DIMENSIONAL MOVEMENT 


v2) 
ll 


1 0 0 cosp O sini cosy -siny 0 
O cosa -sina B = 0) 1 0O C =] siny cosy 0 
O sina cosa -sinf 0 cosB 0 ) 1 


cosBcosy sinasinBcosy—cosasiny cosasinBcosy+sinasiny 
CBA = |] cosfsiny sina sinBsiny+cosacosy cosasinf sin y—sin a cos y 
—sin B sina cos B cos a cos B 


If we have a point on the tetrahedron given by (x, y, z), it is possible to define a 
rotated point based on R using 


x, nS 
( 2 = a( | (4.10) 
Z, Zz 


In this example the tetrahedron appearing in Figure 4.16 will be used and rotated 
using R. 

Figure 4.17 is the MAKE file for the rotating tetrahedron program. Note that 
pprtscr.c is not compiled in this MAKE file and we assume that an object module 
is available at link time. Figure 4.18a is the Structure Chart for this program. Fig- 
ure 4.18b illustrates a flowchart for tetra.c, the main program module. Figure 4.19 
contains the code for tetra.c. This module reads the three angular rates of rotation: 
a, B,, and y,. Also read in is a scale factor for the size of the display image and the 
number of iterations to be rotated. Each iteration assumes an effective time incre- 
ment of dt = 0.05 unit. 
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Figure 4.16 Three-dimensional starting representation for the tetrahedron. 


tetra.obj: tetra.c 
cl -c -Zi -Gs -FPc tetra.c 


rotetra.obj: rotetra.c 
cl -c -Zi -Gs -FPc rotetra.c 


rotmat.obj: rotmat.c 
cl -c -Zi -Gs -FPc rotmat.c 


rotpt.obj]: rotpt.c 
cl -c -Zi -Gs -FPc -Lp rotpt.c 


dmapoint.obj: dmapoint.c 
cl -c -Zi -Gs -FPc -Lp dmapoint.c 


udmapoin.obj: udmapoin.c 
cl -c -Zi -Gs -FPc -F COO -Lp udmapoin.c 


tetra.exe: tetra.obj rotetra.obj rotmat.obj rotpt.obj \ 
dmapoint.obj udmapoin.obj pprtscr.obj cgraph.lib 
link tetra+rotetrat+rotmat+rotpt+dmapoint+udmapoin+pprtscr,,,\ 
slibce.1lib/NOE os2.lib/NOE cgraph.1lib/NOE,, 


Figure 4.17 The MAKE file, tetramak, for the rotating tetrahedron. 
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000 
PROGRAM TO 
CREATE 
ROTATING 
TETRAHEDRON 


100 200 300 


INITIALIZE CALCULATE EXIT 
WINDOW ROTATED WINDOW 
TETRAHEDRON 


110 120 210 


220 


ROTATION SCALING AND GET TRANSLATE 
ANGLES NUMBER OF MESSAGE 


ITERATIONS 


MESSAGE 


Figure 4.18a Structure Chart for the rotating tetrahedron program. 


The module tetra.c contains the usual structures for VioSetMode(). After the 
display and physical buffer selectors are obtained, a call is made to r_tetra(), which 
sets up the new dynamic angle variables and calls rot_tetra(), which appears in 
Figure 4.20. Note that the arrays XX[], YY[], and ZZ[] are used to transfer the 
vertexes of the tetrahedron to rot_point(), where these points undergo the appropri- 
ate rotations. A call rot_mat() sets up the rotation matrix constants. The two func- 
tions DMA point() and uDMApoin() generate and remove the connecting lines, 
respectively. Figure 4.21 illustrates the calculation of the rotation matrix elements 
and should be compared with R in Table 4.1. Figure 4.22 merely completes Equa- 
tion (4.10). 

Figures 4.23 and 4.24 show the routines for accessing the physical screen 
buffer (DMApoint.c) and removing an existing dot on the screen (uDMApoin.c). 
They call wdot() and uwdot(), respectively, which are obtained from the library, 
cgraph.lib (see Figure 4.6). 

Figures 4.25a and 4.25b illustrate the rotating tetrahedron after 100 iterations 
and 50 iterations, respectively. The input values for rates of rotation are a, = B, = 
Y) = 1 and the scale is 60 units. These figures were obtained using prtscr(). 


4.4.2 Plotting Dow Jones Activity 


The major purpose of this example is to illustrate disk access under OS/2. We need 
to recognize that some activities that are performed using the API calls can also be 
performed using the default C library (run time). Disk access is one of these activi- 
ties. 
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SETUP 
DATA 


SET CGA 
MODE 


CLEAR 
SCREEN 


LOCK 
SCREEN 


GET PHYSICAL 
BUFFER SELECTOR 


CACULATE AND PLOT 
ROTATED TETRAHEDRON 


PRINT 
SCREEN 


UNLOCK 
SCREEN BUFFER 


KEYBOARD 
HESITATE 


SET STD 
MODE 


Figure 4.18b Flowchart for tetra.c, 


mil the rotating tetrahedron program. 
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* The routine calls gphrout.c graphics functions. 


#define INCL_BASE 
#include <os2.h> 
#include <stdio.h> 


struct _STRINGINBUF lkbd_buf; 
CHAR kbd_buf[80]; 


UINT action = 0; 
UINT error_code O; 
UINT wait = 1; 


CHAR dstat[1]; 
CHAR dstat1[1]; 


float XX[5] {O0.,1.,0., 
float YY[5] ea eee ee 
float ZZ[5] {On p00. Day 


float x,y,2Z; 

float scale; 

float a[10]; 

float xx1[5],yy1[5]? 
float xxx1[5],yyy1[5]; 
float dt = 0.05; 

int NTOTAL; 


float alpha,beta,gamma,alpha0O,beta0,gamma0; 


col1[320]; 

MM([4] = {0x40,0x10,0x04,0x01)}; 
w(8] = (128,64,32,16,8,4,2,1); 
s[4]; 

shifti[4] = {6,4,2,0}; 
in_buffer1l[4] = {0x1B,0x4B,64,1); 
in_buffer2[2] {Ox0OD, 0x0A}; 
in_buffer3[3] {Ox1B,0x41,8}; 
in_buffer4[2] {0x1B,0x32}; 

dey nane(S] = (*'u','P',*7",*i!, 


extern prtscr(); 


SHANDLE vio_hdl 
SHANDLE kbd_hdl 
UINT wait2 = 1; 
SEL MM1; 


struct _VIOPHYSBUF PVBPrt2; 
struct _VIOMODEINFO CGAm; 


struct _VIOMODEINFO STDm; 


PVBPrt2.pBuf = (BYTE far *) (OxB8000); 


PVBPrt2.cb = 0x4000; 


CGAm.cb = 12; 
CGAm.fbType = 7; 
CGAm.color = 2; 


as 


/* This program gener 


Conditional load */ 


keyboard buf len */ 
keyboard buffer */ 


end thread */ 
result code */ 
reserved word */ 


lock status */ 
lock status */ 


Coords tetra */ 


PrtSc routine */ 


video handle */ 
keyboard handle */ 
reserved */ 

dummy selector */ 


physical buffer */ 
CGA structure */ 


80 x 25 struct */ 


buffer start */ 
buffer size */ 


struct length */ 
CGA mode */ 
CGA color */ 


Figure 4.19 Program code for tetra.c, the main calling program for the rotating 


tetrahedron. 
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CGAm.col = 40; /* text columns */ 
CGAm.row = 25; /* text rows */ 
CGAm.hres = 320; /* CGA hor res */ 
CGAm.vres = 200; /* CGA vert res */ 
STDm.cb = 12; /*® struct length */ 
STDm.fbType = 1; /* 80 X 25 mode */ 
STDm.color = 4; /* STD color */ 
STDm.col = 80; /*® text columns */ 
STDm.row = 25; /* text rows */ 
STDm.hres = 720; /* STD hor res */ 
STDm.vres = 400; /* STD vert res */ 
lkbd_buf.cb = 80; /* buffer size */ 
printf("Input x-rotation rad/sec \n"); 
scanf("%f", &alpha0O) ; 
printf("Input y-rotation rad/sec \n"); 
scanf("%f", &beta0) ; 
printf("Input z-rotation rad/sec \n"); 
scanf("%f", &gamma0O) ; 
printf("Input scale \n") ; 
scanf("%f£",&scale) ; 
printf("Input total no. iterations \n"); 
scanf("%d", &NTOTAL) ; 
/* set CGA mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &CGAm) ,vio_hdl) ; 
cclsCGA(vio_hdl); /* clear CGA screen */ 
VioScrLock(wait2,(char far *)dstat1l,vio_hdl); /* lock screen */ 
/* physical buffer */ 
VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt2,vio_hdl); 
MM1 = PVBPrt2.asel[0]; /* selector */ 
r_tetra(MM1) ; /* tetrahedron */ 
prtscr (MM1) ; /* print screen */ 
VioScrUnLock(vio_hdl) ; /* unlock screen */ 
/* hesitate screen */ 
KbdStringIn((char far *)kbd_buf, 
((struct _STRINGINBUF far *) &lkbd_ buf), 
wait,kbd_hdl); 
/* set STD mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &STDm) ,vio_hdl); 
DosExit (action,error_code) ; 
} 
r_tetra(MM2) 
SEL MM2; 
{ 
int n; 
alpha = 0.; /* x-angle */ 
beta = 0., /* y-angle */ 
gamma = 0; /*® z-angle */ 
for(n = 1l;n <= NTOTAL;n++) 
{ /* dynamic angles */ 


alpha = alpha + alphaO*dt; 
beta = beta + beta0O*dt; 
gamma = gamma + gamma0*dt; 


rot_tetra(alpha,beta,gamma,n-1,MM2) ; /* rotation */ 


Figure 4.19 (Continued) 
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} 


cclsCGA(vio_hdl1) 
SHANDLE vio_hdli; 
{ 
SEL MM; 
UINT waitl = 1; 
struct _VIOPHYSBUF PVBPrt1; /* physical buffer */ 


PVBPrt1.pBuf = (BYTE far *) (OxB8000); /* phys buf start */ 
PVBPrt1l.cb = 0x4000; /* buffer length */ 


VioScrLock(wait1l, (char far *)dstat,vio_hdll); /* lock screen */ 
/* physical buffer */ 
VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt1,vio_hdl1); 


MM = PVBPrtl.asel[0]; /* selector */ 
c1rCGA (MM) ; /* CGA clear */ 


VioScrUnLock(vio_hdl1) ; /* unlock screen */ 


} 


c1rCGA (MM) 
SEL MM; 
{ 
INT n; 
INT Nl Ox1F3F; end odd buffer */ 
INT DM 0x2000; even offset */ 
PCHAR ptr; pointer scr buf */ 


for(n = O;n <= Ni1;ntt+) 


{ 

ptr = MAKEP(MM,n); odd far pointer */ 
eptr = 0; clear odd buffer */ 
} 


for(n = O;n <= N1;nt+) 


{ 
ptr = MAKEP(MM, DM+n) ; even far pointer */ 
*eptr = 0; clear even buffer */ 


} 


Figure 4.19 (Concluded) 


Figure 4.26 presents a routine timhist.c that runs in Protected Mode and func- 
tions identically to its Real Mode counterpart. The program generates a disk file that 
serves aS a time-ordered database. The program accepts three values per record: a 
month, a year, and a tabulated value. The library functions, called in this code 
correspond to the standard C library functions, which are reentrant, hence can be 
used for Protected Mode calls. For the example to be illustrated in subsequent fig- 
ures, this routine was used to create a database of monthly Dow Jones values be- 
tween January 1988 and December 1988. 
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/* Function to rotate tetrahedron */ 


#define INCL BASE 
#include <os2.h> 


rot_tetra(alphal,betal,gammal,N,MM1) 


float alphal,betal,gammal; angles */ 

int N; 

SEL MM1; 

{ 

extern float XX[],YY[],22Z[]; Tetra points */ 
extern float x,y,zZ; point */ 
extern float scale; scaling */ 
extern float xx1[],yyl[]; tetrahedron */ 
int n; 


if(N > 0) 

{ /* Clear tetrahedron */ 
uDMApoin(xx1[1],xx1[2],yy1l[1],yy1[2],MM1) ; 
uDMApoin(xx1[1],xx1[3],yy1[1],yy1[3],MM1); 
uDMApoin(xx1[1],xx1[4],yy1[1],yy1[4],MM1) ; 
uDMApoin(xx1[2],xx1[3],yyl1[2],yy1[3],MM1) ; 
uDMApoin(xx1[2],xx1[4],yyl1[2],yy1[4],MM1) ; 
uDMApoin(xx1[3],xx1[4],yy1[3],yy1[4],MM1) ; 

} 


rot_mat(alphal,betal,gammal) ; /* load rotate */ 


for(n = l;n <= 4;n++) 
{ 
xX = XX[n]; 
4 YY[n]; 
Z 2Z[(n]; 
rot_point(); 
xxl[n] = x*scale + 150.; /* x-projection */ 
yyl{n] = y*scale + 100; /* y-projection */ 


} 
/* Rotate tetrahedron */ 

DMApoint (xx1[1],xx1[2],yy1[1],yy1[2],MM1) ; 
DMApoint (xx1[1],xx1[3],yy1[1],yy1[3],MM1); 
DMApoint (xx1[1],xx1[4],yy1[1],yy1[4],MM1) ; 
DMApoint (xx1[2],xx1[3],yy1[2],yy1[3],MM1); 
DMApoint (xx1[2],xx1[4],yy1[2],yy1[4],MM1); 
DMApoint (xx1[3],xx1[4],yy1[3],yy1[4],MM1) ; 
} 


Figure 4.20 The routine rotetra.c, which sets up the tetrahedron and calls the 
rotation matrices. 
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Figure 4.27 contains the MAKE file for dja.c, which reads the database created 


and generates a plot of the activity. In this case, this activity corresponds to the Dow 
Jones performance. Figure 4.28 presents the actual program code for dja.c. Note the 
needed API calls to clear the screen, plot the graphics, and print the screen. Figure 
4.29 is the prtscr() output for this Dow Jones time history. The curve consists of 
monthly values rounded to the nearest five points. 


The use of fprintf() constitutes the standard I/O call for the disk write and 


works as well in Protected Mode as in Real Mode. IBM and Microsoft have main- 
tained this standard I/O interface within the constraints of OS/2. 
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/* Function to calculate rotation matrix */ 


#include <math.h> 


rot_mat (alpha, beta,gamma) 
float alpha,beta,gamma; 


{ 


extern float a[]?; 
double al1,CA,CB,CG,SA,SB,SG; 


al 
CA 
SA 
al 
CB 
SB 
al 
CG 
SG 


afi] 
a[2] 
a[3] 
a[4] 


(double) (alpha) ; 
cos(al); 
sin(al); 
(double) (beta) ; 
cos(al); 
sin(al); 
(double) (gamma) ; 
cos(al); 
sin(al); 


(float) (CB*CG) ; 
(float) (SA*SB*CG 
(float) (CA*SB*CG 
(float) (CB*SG) ; 
(float) (SA*SB*SG 
(float) (CA*SB*SG 
(float) (-SB) ; 
(float) (SA*CB) ; 
(float) (CA*CB) ; 


/* angles */ 


/* rotation matrix */ 


/* Sines & cosines */ 


/* Matrix elements */ 
CA*SG) ; 
SA*SG) ; 


CA*CG) ; 
SA*CG) ; 


Figure 4.21 The program rotmat.c, which calculates the rotation matrix. 


/* Function to generate rotated point */ 


rot_point() 


extern float x,y,Z; 
extern float a[]; 
float x1,y1,2Z1; 


/* point */ 
/*® rotation matrix */ 
/* intermediate */ 


a[1])*x + a[2]*y + a[3]¥*z; 
a[4]*x + a[5]*y + a[6]*z; 
a[7]*x + a[8]*y + a[9]*z; 


Figure 4.22 The program rotpt.c, which rotates a point. 
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/* This routine plots a connecting line using DMA */ 


#define INCL_BASE 
#include <os2.h> 


DMApoint (x1,x2,y1,y2,MM1) 
float x1,x2,yl1,y2; 
SEL MM1; 
{ 
float m; 
int row; 
int col; 


if (xl == x2) 
m = 1000; /*Upper limit on slope*/ 
else 
m= (y2 - yl)/(x2 - x1); /* normal slope */ 
Lfi(x2 > x1) 
{ 
for (col =(int) (x1)+1; col <= (int) (x2); col++) 
{ /* y-axis behavior */ 
row = (int) (yl + m*(col - x1)); 
wdot (col, row, MM1) ; /* write dot */ 
} 
} 


else 


{ 
if (x2 < xi) 
{ 
for(col =(int) (x2)+1;col <= (int) (x1); col++) 
{ /* y-axis behavior */ 
row = (int) (y2 + m*(col - x2)); 
wdot(col,row,MM1) ; /* write dot */ 
} 


} 
else 
{ 
col = (int) (x1); /* Vertical line */ 
if(yl > y2) 
{ 
for(row = (int) (y2)+l;row <= (int) (yl) ;row++) 
wdot(col,row,MM1) ; /* write dot */ 
} 
else 
{ 
for(row = (int) (yl)+l;row <= (int) (y2) ;rowt+) 
wdot(col,row,MM1) ; /* write dot */ 
} 


Figure 4.23. The program DMApoint.c, which writes a point on the display using DMA. 
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/* This routine removes a connecting line using DMA */ 


#define INC_BASE 
#include <os2.h> 


uDMApoin(x1,x2,y1,y2,MM1) 
float x1,x2,y1,y2; 
SEL MM1; 


{ 

float m; 
int row; 
int col; 


if (xl == x2) 

m = 1000; /*Upper limit on slope*/ 
else 

m= (y2 - yl)/(x2 - x1); /* normal slope */ 
if(x2 > x1) 


for (col =(int) (x1)+1; col <= (int) (x2)? col++) 
{ 
row = (int) (yl + m*(col - x1)); 
uwdot (col, row,MM1) ; /* erase dot */ 
} 
} 


else 
{ 
if(x2 < xi) 
for(col =(int) (x2)+1l;col <=-(int) (x1); col++) 


row = (int) (y2 + m*(col - x2)); 
uwdot (col, row,MM1) ; /* erase dot */ 
} 

} 


else 


{ 
col = (int) (x1); /* Vertical line */ 
if(yl > y2) 
{ 
for(row = (int) (y2)+l;row <= (int) (yl) ;rowt++) 
uwdot (col, row,MM1) ; /* erase dot */ 


} 


else 
{ 
for(row = (int) (yl)+l;row <= (int) (y2) ;row++) 
uwdot (col, row,MM1) ; /* erase dot */ 


Figure 4.24 The program uDMApoin.c, which removes a point from the 
display using DMA. 


(a) (b) 


Figure 4.25 (a) The tetrahedron after 100 iterations with and scale = 60. 
(b) The tetrahedron after 50 iterations with and scale = 60. 
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/* Routine to create time-history/value database -- timhist.c*/ 


#include <stdio.h> /* I/O file */ 


int month[288],year[288]; /* time arrays */ 
float value[288]; /* quant. interest */ 
char FN1[81]; /* filename array */ 


main() 
{ 
int n,counter, check; /* integer var. */ 
FILE *outfile; /* stream pointer */ 


printf("Input database filename \n"); 

gets(FN1) ; /* library routine */ 
n= 1; /* initialize index */ 
month[0O] = 1; /* init month not 0 */ 
while(month[n-1] != 0) 


printf("Input month as int (0 terminates) \n") ; 
scanf("%d", &month[n}) ; 
if(month[{n] != 0) 

{ 

printf("Input year as 2-digit int\n"); 

scanf("%d",&year[n]); 

printf("Input value - floating point\n") ; 

scanf ("%f", &value[n]}) ; 

} 
nt++; increment index */ 
if(n > 288) 

exit(1); overflow mem */ 
} 


counter =n - 2; fix count */ 


if((outfile = fopen(FN1,"w")) == NULL) open out file */ 
{ 
printf("Output file failure: %s",FN1); 
exit(1); 


fprintf(outfile,"%d ",counter) ; /* output count */ 
for(n = l;n <= counter;n++) 
fprintf(outfile,"%d *d *f ",month[n],year[n],value[n}) ; 


if((check = fclose(outfile)) != 0) /* close file */ 
{ 
printf("Error in output file close"); 
exit(1); 
} 


Figure 4.26 The routine timhist.c, which creates a data file consisting of dates 
and values. 


dja.obj: dja.c 
cl -c -Zi -Gs -FPc -F COO -Lp dja.c 


dja.exe: dja.obj pprtscr.obj cgraph.lib 
link dja+pprtscr,,,\ 
slibce.1lib/NOE os2.1lib/NOE cgraph.lib/NOE,, 


Figure 4.27 The MAKE file for dja.c, which plots the Dow Jones activity 
generated by timhist.c. 


Sec. 4.4 Other Programs 


#define INCL_BASE 
#include <stdio.h> 
#include <os2.h> 
#include <math.h> 
#include <stdlib.h> 


int month[{288],year[288]; 
float value[288]; 

char FN1[81]; 

float xx[1024]; 

char buffer([(90],buffer1[90]; 


struct _STRINGINBUF lkbd_buf; 
CHAR kbd_buf[80]; 


UINT action = 0; 
UINT error_code = 0; 
UINT wait = 1; 


CHAR dstat[1]; 
CHAR dstatl1[1]; 


col1[320]; 

MM[4] = {0x40,0x10,0x04,0x01}; 
w[8] = {128,64,32,16,8,4,2,1}; 
s[4]; 

shift1[4] = {6,4,2,0}; 
in_buffer1[4] {0x1B,0x4B,64,1); 
in_buffer2[2] {Ox0OD,0x0A}; 
in_buffer3[3] {Ox1B,0x41,8}; 
in_buffer4[2] {0x1B,0x32}; 
dev_name[5] = {'L','P','T*,'1',0}3 


int n,counter,check,N,i,delta,nmaxs,nmins; 
FILE *infile; 

double x,y,Z; 

float maxt,mint,b,bl1; 


extern prtscr(); 


SHANDLE vio_hdl 
SHANDLE kbd_hdl 
UINT wait2 = 1; 
SEL MM1; 


struct _VIOPHYSBUF PVBPrt2; 
struct _VIOMODEINFO CGAm; 


struct _VIOMODEINFO STDm; 


PVBPrt2.pBuf = (BYTE far *) (0xB8000); 
PVBPrt2.cb = 0x4000; 


CGAm.cb = 12; 
CGAm.fbType = 7; 
CGAm.color = 2; 
CGAm.col = 
CGAm.row = 25; 


Figure 4.28 The program dja.c, which plots the Dow 


/* Routine to read Do 


time arrays */ 
quantity */ 
filename array */ 
Scratch buffers */ 


keyboard buf len */ 
keyboard buffer */ 


end thread */ 
result code */ 
reserved word */ 


lock status */ 
lock status */ 


integer var. */ 
stream pointer */ 


print screen */ 


video handle */ 
keyboard handle */ 
reserved */ 

dummy selector */ 


physical buffer */ 
CGA structure */ 


80 x 25 struct */ 


buffer start */ 
buffer size */ 


struct length */ 
CGA mode */ 

CGA color */ 
text columns */ 
text rows */ 


Jones activity. 
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214 


CGAm. hres 
CGAm.vres 


STDm.cb = 
STDm.fbType = 
STDm.color 


STDm.col 
STDm. row 


STDm. hres 
STDm.vres 


320; 
200; 


12; 


lkbd_buf.cb = 


printf("Input database filename\n") ; 
gets(FN1); 


if((infile 


{ 


= fopen(FN1,"r")) == NULL) 


printf("Input file failure: %s",FN1) ; 
exit(1); 


fscanf(infile,"%d ",&counter) ; 


for(n = 


{ 


lzn <= counter;nt+t+) 


OS/2 and C 


CGA hor res */ 
CGA vert res */ 


struct length */ 
80 x 25 mode */ 
STD color */ 
text columns */ 
text rows */ 

STD hor res */ 
STD vert res */ 


buffer size */ 


library routine */ 


no. records */ 


fscanf(infile,"%td td *f ",&month[n],&year[n],&value[n]}) ; 
printf("%5d 5d %6.0f \n",month[n],year[n],value[n)]) ; 


} 
if((check = fclose(infile)) != 0) 


{ 


printf("Error in input file close") ; 
exit(1); 


} 


mint 


1.e4; 


maxt 0.0; 


N = counter; 


for(i = 


{ 


if (maxt 
maxt 
if (mint 
mint 


} 


delta 
delta 
if(delta 
delta 
if (delta 
delta 
if (delta 
delta 
if (delta 
delta 
if (delta 
delta 
if(delta 
delta 
if (delta 
{ 


A 


vVvivievivievievid 


l;i <= N;itt) 


value[i]) 
value[i]; 
value[i]) 
value[i]; 


< 
> 


maxt - mint; 
delta/10; 


1) 

1; 

1 && delta < 5) 

5; 

5 && delta < 10) 
10; 

10 && delta < 50) 
50; 

50 && delta < 100) 
100; 

100 && delta < 500) 
500; 

500) 


printf(" delta > 500"); 
exit(1); 


} 


nmaxs 
nmins 


maxt/delta + 1; 
mint/delta; 


Figure 4.28 


(Continued) 


reverse limit */ 
reverse limit */ 


max/min */ 


Set scale */ 
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maxt delta*nmaxs; 
mint = delta*nmins; 
if(mint <= 0) 
mint = mint - delta; /* scaled min */ 


x mint; /* scaled max */ 
y fabs (x); 
Z (float) (y);? 
bl = (z)/((float) (x)); 
if(maxt > z && bl < 0) 
mint = -maxt; 
else 


{ 
if(maxt < z && bl < 0) 
maxt = Z; 


} 


b = 150./(maxt - mint); /* plot coords */ 
for(i = 1;i <= N;it++) 

{ 

value[i] = 25. + (150. - b*(value[i] - mint)); 

xx[i] = 25. + (i - 1)*(256./(float) (N)); 

} 


/* CGA mode */ 
VioSetMode(((struct _VIOMODEINFO far*) &CGAm) ,vio_hdl) ; 


cclsCGA(vio_hdl) ; /* clear screen */ 
VioScrLock(wait2, (char far *)dstat1,vio_hdl); /* lock buffer */ 


/* get physical buf */ 
VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt2,vio_hdl); 


MM1 = PVBPrt2.asel[0]; /* selector */ 
box_norm(MM1) ; /*® plot box */ 
/* plot points */ 


for (n=1;n<=(N-1) ;n++) 
pltpt(xx[n],xx[n+1],value[n],value[n+1],MM1) ; 


prtscr (MM1) ; /* print screen */ 


VioScrUnLock(vio_hdl) ; /* unlock buffer */ 


KbdStringIn((char far *)kbd buf, /* hesitate */ 
((struct _STRINGINBUF far *)&lkbd_buf), 
wait,kbd_hdl); 


/* STD mode */ 
VioSetMode(((struct _VIOMODEINFO far *)&STDm) ,vio_hdl); 


DosExit (action,error_code) ; 


} 


box_norm(SEL MM) 


{ 
int xxbeg,xxend,yybeg,yyend; 


25; /* box parameters */ 
281; 
25; 
175; 


xxbeg 
xxend 
yybeg 
yyend 


bboxx (xxbeg, xxend, yybeg, yyend, MM) ; /* Araw box */ 
} 


Figure 4.28 (Continued) 
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cclsCGA(SHANDLE vio_hdl1) 
{ 
SEL MM; 
UINT waitl = 1; 
struct _VIOPHYSBUF PVBPrt1; physical buffer */ 


PVBPrt1.pBuf = (BYTE far *) (OxB8000) ; phys buf start */ 
PVBPrt1l.cb = 0x4000; buffer length */ 


VioScrLock(wait1, (char far *)dstat,vio_hdll) ; lock screen */ 


VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt1,vio_hdll) ; 


MM = PVBPrtl.asel[0]; /* selector */ 
c1rCGA (MM) ; /* CGA clear */ 


VioScrUnLock(vio_hdll) ; /7* unlock buffer */ 
} 


clrCGA(SEL MM) 
{ 
int ns 
int Nl = Ox1F3F; end odd buffer */ 
int DM = 0x2000; even offset */ 
PCHAR ptr; pointer scr buf */ 


for(n = O;n <= N1;n++) 
{ 
ptr = MAKEP(MM,n); odd far pointer */ 
*ptr = 0; clear odd buffer */ 
} 


for(n = O;n <= Nl1;nt+t+) 
{ 
ptr = MAKEP(MM, DM+n) ; even far pointer */ 
*eptr = 0; clear even buffer */ 


) 


Figure 4.28 (Concluded) 


Dow Jones Industrials 
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Figure 4.29 Annotated plot of Dow Jones activity through the October 1987 
crash. 
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4.5 SUMMARY 


This chapter has served to illustrate the OS/2 and C programming language inter- 
face. C represents a higher degree of abstraction than does assembler. The IBM 
Toolkit provides a complete set of types and API function prototypes to permit high- 
level access to the API services. The low-level nature of these services is illustrated 
in the C context. 

Graphics under C are developed and a new print screen routine in C is pre- 
sented that allows a screen dump in graphics mode. This screen dump program is 
designed for operation with CGA mode. The standard C syntax is presented and a 
knowledge of this syntax is assumed as a prerequisite to understanding the chapter. 

The creation of multitasking routines is developed using multiple threads and 
processes. Finally, the issues associated with programming multitasked routines in C 
are developed through program examples. This chapter is necessarily introductory 
and establishes a basis for programming OS/2 applications using the C language. 
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PROBLEMS 


4.1 When using the IBM Toolkit definitions, what precaution must be used between Ver- 
sions 1.0 and 1.1? 

4.2 What are the implications for the standard C I/O library running under the Protected 
Mode of OS/2? 

4.3 The Version 5.1 of the Microsoft C Optimizing Compiler passes formal parameters 
with type specifications for these parameters appearing in the function definition. 
Typically, a function definition such as 
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4.4 
4.5 


4.6 


4.7 
4.8 


4.9 


4.10 
4.11 


4.12 
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INT box_norm(waitt, float x, float y) 


replaces 


INT box _norm(waitt, x, y) 
INT waitt; 
float x,y; 


The type specification moves within the formal parameter list itself. What characteris- 
tic of this type definition remains consistent across formal parameter types? 


In Figure 4.1, why must the input word integer be less than 32,768? 


The OS/2 references dictate the manner in which the API services must be loaded on 
the stack. Using the normal C calling convention, what parameter access on the local 
stack exists? How does the Toolkit modify the API calls to load the local stack cor- 
rectly for access? 


What does the syntax 
CHAR FAR *ptr; 


mean? Why is the following acceptable? 


CHAR FAR *shrname = “”\\SHAREMEM\\SDAT1.DAT”; 


What does the function MAKEP (sel,off) accomplish? 
In Figure 4.5b, what is the significance of the following? 


PVBPrt2.pBuf = (BYTE far *)(0xB8000); 
What is wrong with the code 

esas VY? 

double t; 

i . sin(2.* PI *t); 

Assume that PI is defined as 


#define PI 3.141592654 


What differentiates uwdot() from wdot()? (See Figure 4.6.) 
In pltpt() and upltpt() (Figure 4.6) the x-values are associated with column values and 
the y-values are associated with row values. Explain. 


In setting up the printer for a dump of the display, the following command is used 
(Figure 4.9b): 
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4.13 


4.14 
4.15 


4.16 


4.17 
4.18 
4.19 


4.20 


4.21 


DosWrite(dev_hand,in_buffer,bytesinl, (PUSHORT) &bytesort) ; 


Here bytesin1 = 4 and 
BYTE in_bufferl[4] = {0x1B,0x4B,64,1}; 


What is the significance of this output value? 


What is the meaning of the DosWrite() execution in Figure 4.9b with in_buffer3]] 
defined as 


BYTE in buffer3[3] = {0x1B,0x41,8}; 


In Figure 4.11b, are the semaphores used RAM semaphores or system semaphores? 


What is characteristic about all the API function calls and their associated formal 
parameters? 


What is the generic mechanism used by the semaphore calling sequence to ensure 
synchronization between two processes? Between two threads? 


In Figure 4.12, what is the purpose of accessing the shared segment? 
When creating a thread within a process, how is the thread’s stack handled? 


Throughout the examples of this chapter, error checking for such actions as creating a 
thread have been deleted from the basic code. Please comment on this lack of error 
checking intrinsic to the programs. 

In the program tetra.c (Figure 4.19), what are the basic vertex points used for the 
tetrahedron? 


In Figure 4.28, where does the routine dja.c acquire the function bboxx()? 


5 Additional OS/2 
Considerations 


In Chapter 4, C programming for the OS/2 full-screen mode was presented. We saw 
that the C code required low-level access for many operations that call API func- 
tions. C has the advantages afforded high-level languages as well as low-level ac- 
cess to the operating system via these API services. Hence C is an ideal candidate 
language for programming OS/2. Occasionally, a need will exist for generating a 
special-purpose routine in assembly language and interfacing it to C program code. 
The methodology for accomplishing this is discussed in Section 5.1. 

The Microsoft linker, which comes with the C compiler utilities, serves to load 
and link the object modules required by a program. When an .exe program is gen- 
erated by the linker, all needed object modules must be input to the link process. 
This can be cumbersome, especially when large library files are called by the linker. 
OS/2 possesses the capability for two types of dynamic linking using dynamic 
linked libraries (DLL), where external references can be resolved by means other 
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than the static linking normally employed. DLL satisfy external references either 
during loading, load-time linking, or at run-time, run-time linking. In the former case 
all external references are satisfied by the linker through knowledge of where the 
DLL routines reside. In this case a priori knowledge about the location of the 
needed DLL routines exists even though these routines are not located within the 
.exe module at linking. When a program begins execution the DLL routines are 
loaded, when called, based on this knowledge of where these routines reside. In run- 
time linking, the DLL routines are located at the time they are called and then 
loaded. The latter approach takes slightly longer than load-time linking but leaves 
the basic executable module unencumbered. 

Why would OS/2 implement dynamic linked libraries? Primarily because of 
the multitasking feature. Since multitasking and memory management require move- 
ment into and out of memory, it is desirable to keep executable modules as small as 
possible. DLL management is one technique for achieving small executable modules. 
In Section 5.2 we address DLL implementation. In the remainder of the chapter we 
consider programming conventions, take a brief additional look at the API, and 
study a representative C example. 


5.1 MIXED-LANGUAGE PROGRAMMING AND OS/2 


We have seen how both assembly language and C code can be used for program- 
ming under OS/2. C code is preferred as the level of abstraction or task complex- 
ity increases. C, however, yields less optimized object code than does assembly lan- 
guage programming. Hence for critical applications, C routines must be interfaced 
to assembly language modules. This is particularly true when hardware is to be 
accessed directly or execution speed is important. In this section, where we address 
the integration of C and assembler, we will assume that the C modules call assem- 
bler modules when appropriate. 
Assembler has a basic template for setup to interface to Microsoft C: 


TLILLE s+ 
7 
; Description... 


a 
_DATA1 SEGMENT BYTE PUBLIC ‘DATA’ 
PUBLIC _VARI,... 


_DATA1 ENDS 
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_TEXT SEGMENT BYTE PUBLIC ‘CODE’ 
ASSUME CS: _TEXT,DS: DATAI1 
PUBLIC _Function* 
_Function PROC NEAR 
PUSH BP 
MOV BP,SP 
SUB SP,10 
PUSH BX 
PUSH CX 
PUSH DX 
PUSH SI 
PUSH DI 


PUSH DS 
MOV AX,SEG _DATAI1 
MOV DS,AX 


(main body) 
MOV AX, cc. 
POP DS 
POP DI 
POP SI 
POP DX 
POP Cx 
POP Bx 
MOV SP,BP 
POP BP 
RET 
_Function ENDP 
TEXT ENDS 
EMD 


To interpret this template, consider first the segment definitions. Two segments 
are defined: TEXT and DATAI, the code segment and the data segment, respec- 
tively. The data segment is not_DATA because all parameters from the calling data 
segment will be passed using the stack. Hence there is no need to keep the “old” 
data segment during execution of the assembler code. The new segment, DATAI, 
is optional as needed. Following definition of the segment registers using ASSUME, 
a procedure, Function, is defined. This function must be PUBLIC so that it can be 
called externally. Upon entry to the procedure, a return address will be pushed on 
the stack. This address is an offset (2 bytes) for NEAR calls. After the call the 
calling routine has its frame pointer in the BP register. This pointer serves as the 
basis for moving from frame to frame. The template requires pushing this address on 
the stack. Four bytes now reside on the stack for a NEAR call. The stack pointer 
now contains the new frame pointer, which is loaded into BP, and space is allocated 


224 Additional OS/2 Considerations Chap. 5 


on the stack by advancing the stack pointer 10 bytes (as an example). These steps 
are accomplished with the code 


PUSH BP 
MOV BP,SP 
SUB SP,10 


Next, the general-purpose registers (except AX) and the index registers are pushed 
on the stack. Finally, the old data segment address (appearing in DS) is saved on the 
stack and a new data segment address for DATAI1 is loaded into DS. 

The parameters passed to the assembler reside starting at [BP+4] because a 
return address and a frame pointer have been loaded. Assuming that all parameters 
are of type int, they will reference as [BP+4], [BP+6], [BP+8], and so on. Clearly, 
other data types will occupy space accordingly. The return values from the assem- 
bler routine will occupy AX or AX and DX. At this point all pushed registers are 
popped, the caller’s frame pointer restored, and the return address accessed. This, 
then, briefly describes the template for interfacing assembler to C. 

Figure 5.1 illustrates a C program that reads an upper and lower frequency, a 
number of iterations, and an individual tone duration (in milliseconds). The program 
generates a musical or tone scale at intervals of 100 Hz for the range of frequencies 
spanned by the upper and lower frequencies. This C program calls an assembly 
language routine, scales1(), which accesses the tone generator. This assembly lan- 
guage routine appears in Figure 5.2 and follows the normal assembly language 
template for the C interface [1]. Note that the main portion of this routine simply 
passes the formal parameters to @DosBeep. In this case the frequency, freq, is 
passed at [BP+4] and the duration, dduration, is passed at [BP+6]. The inclusion 


IF1 
include sysmac.inc 


ENDIF 


loads the API services as required. 


The routine scalesl.asm, which appears in Figure 5.2, was assembled with the 
instruction 


masm scalesl 

The C program appearing in Figure 5.1 was compiled using 
cl -c -Zi; scales.c 

The linking was accomplished as 


link scales+scalesl, scales,,doscalls,,,/CO 
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/* This program generates scales and 
* calls an assembler routine */ 


#define INCL_BASE 
#include <os2.h> 
#include <stdio.h> 


UINT low_freq,high_freq,no_iterations,dduration; 


UINT action = 0; 
UINT error_code = 0; 


main() 


{ 


printf("Input lower frequency (Hz) - integer\n") ; 


scanf ("%d", &low_freq) ; 


printf("Input higher frequency (Hz):- integer\n") ; 


scanf("%d", &high_ freq) ; 

printf("Input number iterations \n"); 
scanf("%d",&no_ iterations) ; 
printf("Input component duration \n"); 
scanf ("%d", &dduration) ; 


sscale(); 


DosExit(action,error_code) ; 


} 


sscale() 


{ 


extern scalesl1()j; 
int freq,n,m,N; 


low_freq 
low_freq 


low_freq/100; 
low_freq * 100; 


if(low_freq <= 100) 
low_freq = 200; 


high_freq/100; 
high_freq * 100; 


high_freq 
high_freq 


m 0; 
N (high_freq - low_freq)/100; 


while(m <= no_iterations) 

{ 

for(n = 1l;n <= N;n++) 
{ 
freq = low_freq + n *100; 
scales1(freq,dduration) ; 
} 

for(n = 17n <= N;nt+) 
{ 
freq = high_freq - n * 100; 
scalesl1(freq,dduration) ; 
} 

m++; 


} 


tone generator */ 


assembler module */ 


normalize */ 


minimum set */ 
normalize */ 
initialize loop */ 
no. tone points */ 
check limit */ 
up-scale */ 


set frequency */ 
tone */ 


down-scale */ 
set frequency */ 


tone */ 
increment loop */ 


Figure 5.1 C program to generate musical scale based on input frequencies and 


time duration. 
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PAGE 40,132 
TITLE scalesl1 - Routine to generate scales (saclesl.asm) 


DESCRIPTION: This routine generates various tones. 
[BP+4] contains the frequency and [BP+6] contains 
the duration in millisec. 


include sysmac.inc 


SEGMENT BYTE PUBLIC 'CODE' 
ASSUME CS:_TEXT 
PUBLIC _scales1l 

_scalesl PROC NEAR 


push BP 
mov BP,SP 
sub SP,8 
push DI 
push SI 
push AX 
push BX 
push CX 
push DX 
;Begin beep 
@DosBeep [BP+4],[BP+6] 
pop Dx 
pop Cx 
pop BX 
pop AX 
pop SI 
pop DI 
mov SP,BP 
pop BP 


Tet 
_scalesl 
_TEXT ENDS 

END 


Figure 5.2 C-callable assembly language routine to generate tonals. 


5.2 DYNAMIC LINKING AND RESOURCE MANAGEMENT 


Dynamic linking is a method of generating an executable program where not all 
modules are loaded into the execute file at link time but are loaded on demand 
during execution [2]. Under OS/2 a single code segment can be accessed by mul- 
tiple programs, and such reentrant code facilitates dynamic linked library (DLL) 
usage, where simultaneous access of a library routine is possible. This is in keeping 
with the goal of minimizing code in a multitasking environment. 

The two types of dynamic linking, load-time linking and run-time linking, 
serve distinctly different needs. Load-time linking involves complete knowledge of 
where a needed external routine resides prior to execution and is appropriate for fre- 
quently used routines. Run-time linking requires locating and installing external 
routines upon their call from an executing program. This form of linking is used 
primarily for accessing routines on an infrequent basis. 
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5.2.1 Using Dynamic Linked Libraries 


We have seen that dynamic linked libraries (DLL) are useful when it is desirable to 
minimize the amount of code linked with multiple executable routines or tasks in a 
multitasking environment. It is in support of multitasking that DLL can contribute 
significantly. The run-time dynamic linking circumvents this situation where a DLL 
can be released from an executable module. | 

There are actually three types of linked modules possible when dynamic link- 
ing is employed: 


1. Load-time dynamic Linking 
a. Preloaded DLL 
b. Load on Call DLL 

2. Run-time dynamic Linking 
a. Explicit Load and Call 


To fully appreciate the nuances among these options, we must examine the concept 
of a definition file, where one of these options is determined for each DLL imple- 
mentation. Briefly, the preloaded DLL requires that these DLL routines be loaded at 
the start of execution. The load on call DLL implies that the code be loaded as each 
DLL routine is called by the executing program using guidance in the definition file. 
Finally, the explicit load and call situation for run-time dynamic linking requires that 
the DLL be accessed using API services. We will consider each type of DLL access 
in Section 5.2.4. 

The LINK utility is used to join object routines into executable modules that 
have all their external references accounted for. The linker is used to create either 
a DLL or an executable, .exe, file. How does this work? Basically, the module 
definition file (.def) specifies whether or not a particular output (from the linker) is 
to be a DLL or an .exe file. This definition file also includes a number of statements 
that can be used to tailor executable code to accomplish various optimizations. It in- 
cludes information that distinguishes between a DLL or application, a list of im- 
ported and exported functions (see below), the size of the stack and heap, and a 
number of options for the code and data segments. The latter option allows speci- 
fication of whether or not segments are to be preloaded or loaded on demand. When 
using the linker we have noticed that a prompt for a definition file always occurs as 
the last entry in the linker prompt sequence. So far we have left this entry blank, 
which is an appropriate default for applications. We will now use this prompt to 
supply a .def file where appropriate. 


5.2.2 The Definition File 


Table 5.1 illustrates the allowed (and in some cases the mutually exclusive) state- 
ments that can appear in the module definition file. The first two statements are 
either NAME or LIBRARY. The former specifies the name of an application (.exe) 
and the latter specifies the name of a DLL (.dll). The description (DESCRIPTION) 
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merely states in prose the module purpose. The statement PROTMODE specifies 
that a module is to run under Protected Mode. The statement 


CODE [load][shared] [execute] [privilege] 


is used to define the default attributes for all the module’s code segments. Subse- 
quent statements using the SEGMENTS key word can override this statement 
(CODE) to tailor segment usage. In the CODE statement above, [load] is used to 
specify whether or not the code segments are physically loaded at the start of exe- 
cution or on demand. This option has two possible values: PRELOAD (for loading 
at start of execution) and LOADONCALL (for demand loading). 

The next option, [shared], specifies whether code segments in a DLL are to be 
accessed by all tasks needing these segments as a single instance or as multiple 
instances (where duplicate copies of the DLL routine are generated). This option has 
two possible values: SHARED (where only one copy of the code segment exists) or 
NONSHARED (where a unique copy of the code segments is loaded for each ref- 
erence). The option [execute] allows code segments to remain distinct through the 
value EXECUTEONLY. In this case the code segment selector cannot be loaded 
into DS. The alternative value, EXECUTEREAD, permits the segment selector to be 
loaded into DS. Finally, [privilege] is used to give code segments I/O privilege at 
level 2 by having IOPL specified. 


TABLE 5.1 MODULE DEFINITION FILE STATEMENTS 


Statement Comments 
NAME Declares a module as an application 
LIBRARY Declares a module as a DLL module 
DESCRIPTION Defines module descriptively 
PROTMODE Declares a module as a Protected Mode routine 


CODE [load][shared][execute]|privilege] 


[load]: specified whether code loaded at the start of execution 
(PRELOAD) or on demand (LOADONCALL) 

[shared]: one copy of code loaded (SHARED) or multiple 
copies loaded with tasks (NONSHARED) 

[execute]: (EXECUTEONLY)—code segments can only be 
executed; or (EXECUTEREAD)—they can be read as well 

[privilege]: allows code segment I/O capability 
(IOPL) 

DATA [load][instance][shared][write][privilege] 

[load]: specifies whether code loaded at the start of execution 
(PRELOAD) or on demand (LOADONCALL) 

[instance]: no automatic data segment created (NONE), all 
instances share the same automatic data segment 
(SINGLE),and multiple copies for each instance (MULTI- 
PLE) 

[shared]: same copy of a segment shared (SHARED) and new 
copies loaded for each instance (NONSHARED) 
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TABLE 5.1 (Concluded) 


Statement Comments 


[write]: specifies that a memory segment can be written to 


(READWRITE) or only read (READONLY) 
SEGMENTS [segname][CLASS(‘classname’)][minalloc][segflags] 
[segname]: name of segment whose attributes are to be 
changed 


[classname]: ‘CODE’ or ‘DATA’ 
[minalloc]: minimum number of bytes reserved for segment 
[segflags]: attributes assigned to segment 


IMPORTS [intname]modulename.[entryname or entryordinal] 
[intname]: name to be used within importing module 
modulename: application library that contains functions 
[entryname]: entry point to DLL routine 
[entryordinal]: DLL routine ordinal position 


EXPORTSentryname[=intname][@ordinal][RESIDENTNAME][NODATA Jargnum 

entryname: name to be used by accessing routines 

[intname]: real name of routine 

[@ordinal]: defines the routine’s ordinal value within export 
module 

[RESIDENTNAME]: used with @ordinal argument to specify 
resident always 

[NODATA]: if present, specifies no stack or automatic data 


segment 
argnum: number of parameters to be received or IOPL 
STACKSIZE Number of bytes an application or DLL needs for its own 
stack 
HEAPSIZE Number of bytes in application or DLL heap 
STUB Name of a DOS 3.x program to replace an application or 


library invoked in Real Mode instead of correctly specify- 
ing Protected Mode 


The statement 
DATA [load][instance] [shared] [write] [privilege] 


is used to specify the default attributes for all the module’s data segments. The first, 
[load], is the same as for the CODE statement except that LOADONCALL is the 
default option when no load argument is specified. The option [instance] describes 
the automatic data segment, which is the physical segments(s) represented by the 
name dgroup. This segment(s) contains the local heap and stack area for an appli- 
cation. It can take one of three values: NONE (no automatic segment), SINGLE (all 
application instances share the same automatic data segment), and MULTIPLE (de- 
fault value where each instance has its own automatic data segment). 

The argument [shared] parallels the [instance] value. It has two values: 
SHARED (same copy of a segment is shared by multiple instances of an applica- 
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tion) and NONSHARED (new copies of data segments are loaded for each instance 
of an application; this is the default value). The [shared] argument and the [in- 
stance] argument must match. If a conflict arises, all segments in dgroup are shared, 
and all others are nonshared. 

The argument [write] specifies whether the data segments can be written to or 
not: READONLY (cannot be written) and READWRITE (default option; the seg- 
ment can be written to as well as read). The argument [privilege] is the same as for 
CODE. The statement 


SEGMENTS 
[segname] [CLASS( ‘classname’ ) ][minalloc] [segflags] 


is used to assign attributes individually to code or data segments. The parameter 
[segname] denotes the segment label and can be declared as ‘CODE’ or ‘DATA’ via 
the classname. The default is ‘CODE’. Each segment is allocated a minimum 
number of bytes: [minalloc]. The argument [segflags] can be any combination of 
arguments specified above with CODE or DATA segments. 

The form of the IMPORTS statement is 


IMPORTS 
[intname] modulename. [entryname|entryordinal] 


Here intname specifies the internally used name of the importing module as it calls 
an external entry point (the ASCII string, entryname, within the DLL). The parame- 
ter modulename is the name of the application or DLL containing the needed func- 
tions, and entryordinal merely identifies entryname by its ordinal position with the 
DLL, 

The form of the EXPORTS statement is 


EXPORTS 
entryname[=intname] [@ordinal] [RESIDENTNAME ] [NODATA]argnum 


This statement defines the routines within a DLL or application that are to be 
available for other programs. Alternatively, it can be used to specify routines that are 
to have level 2 I/O privileges. The argument entryname defines the name that call- 
ing modules will use when accessing the exported routine. The parameter [=intname] 
is the real name appearing in the exporting routine. The [@ordinal] parameter de- 
fines the routine’s ordinal value within the module. 

The argument [RESIDENTNAME] is used only when [@ordinal] is specified 
and it indicates that the function’s name must be resident at all times and, conse- 
quently, the name and ordinal value will be stored in the DLL export table. The 
[NODATA] argument means that the export routines will have neither a stack nor 
an automatic data segment. Finally, argnum takes on the value IOPL when the ex- 
port routine is to have level 2 privilege. 

STACKSIZE specifies the number of bytes an application or DLL needs for 
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the local stack. Similarly, HEAPSIZE specifies the number of bytes an application 
or DLL needs for its local heap. STUB specifies the name of a DOS executable file 
to be run in place of a Protected Mode application or library when such applications 
or libraries are invoked under Real Mode. 


5.2.3 Creating a DLL 


In the preceding section we saw examples of the use of IMPORT and EXPORT in 
the definition file. IMPORT specifies the routines that will be used by an executable 
file and incorporated at load or run time, as indicated in the application definition 
file. EXPORTS specifies the routines that will be transferred to the executable file 
at load or run time from the DLL, as indicated in the DLL definition file. 

To see this work, consider the creation of a DLL and its incorporation with 
other modules. The following sequence of steps corresponds to Example 1 in Sec- 
tion 5.2.4, where the program code will be specified: 


link dyninit.obj dlinkl.obj, dynll.dll, doscalls.lib, dynll,def 


This link statement links dyninit and dlink1 (both object modules) to create dyn11. 
We assume that dynl1.def has the LIBRARY option with dyn11 specified. Then the 
created routine has the .dll extension, denoting it as a dynamic linked library. The 
single library, doscalls.lib, imports the API service routines. Hence, from the fore- 
going process comes the DLL, dyn11.dll. 

Dynamic linked libraries must be linked with applications as libraries, not .dll 
files. Hence the import library utility, implib, can be used to create this library based 
on the definition file. The routines above, for example, are in dyn11.dll, but the 
entry points can be specified in dyn11.lib, which is created as follows: 


implib dynll.lib dynll.def 


Here implib creates dyn11.lib, which has the entry points specified by the EXPORT 
table in dyn11.def. 

The last step is to create the application run file and satisfy all external refer- 
ences through library access (as an example). Assume that the application exists as 
an object module named dyn1.obj. The link procedures will be 


link dynl.obj, dynl.exe,,doscalls.lib dynll.1ib,, 


Here dynl.exe is the output for dynl.obj and uses both doscalls.lib (the API serv- 
ice) and dyn11.lib (the library file for the DLL). During execution of dynl.exe the 
DLL routines will be accessed via the dyn11.lib table (these DLL routines reside in 
dyn11.dll). 

The importance of specifying EXPORT and IMPORT files should now be 
clear. It is the only way of identifying DLL routines to the implib utilities that create 
the DLL needed library file. This file points to the available DLL routines (this file 
is output from implib with extension .lib). 
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5.2.4 DLL Examples 


In the preceding section we outlined how to create a DLL using an appropriately 
constructed module definition file. Both the link and implib utilities were used in 
this process. File names were specified without actually presenting the files them- 
selves, in order that the mechanics of the linking process could be illustrated. By 
way of introducing an example, the code is now presented for the files in question. 


Example 1. Figure 5.3 shows the main application program, dynl.asm, which 


PAGE 40,132 
TITLE DYN1 - Main calling program example #1 (dynl.asm) 


’ 


; DESCRIPTION: This program calls dynll.dll to demonstrate 
; preloaded assembler dynamic link libraries. 


-286cC 
-sall ;Suppresses macro lists 


-xlist 
INCL BASE equ 1 
include 0OS2.INC 
est 


extrn dlink1:FAR 
' 
dgroup GROUP data ;defines automatic data seg 


’ 

STACK SEGMENT PARA STACK 'STACK' 
db 64 dup('STACK ©) 

STACK ENDS 


’ 
data SEGMENT PARA PUBLIC 'DATA' 


msgl db "Dynamic Link Pre-loaded Routine',ODH, OAH 
msgl1_1 equ &-msgl 

msg2 db ‘Error on access DLL',ODH, OAH 

msg2_l1 equ $-msg2 


action equ 0 ;code to end thread 
result dw fe) ;return code for error 
vio_hdl equ 0) ;video handle 


data ENDS 


CSEG SEGMENT PARA PUBLIC 'CODE'! 
ASSUME CS:CSEG,DS:dgroup 
DYN1 PROC FAR 


push ds ;push message segment 
lea bx,msg ;offset of message 
push bx ;save offset 

push msgl1_l ;message length 


call dlinkl ;DLL routine to print msg 


cmp ax,0 ;check for error 
je EXIT jump if OK 
@VioWrtTTY msg2,msg2_1,vio_hdl 


8 
’ 


@DosExit action,result 
ENDP 

ENDS 

END DYN1 


Figure 5.3. Main dynamic link library calling program, illustrating preloaded 
DLL routines. 
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imports routines from the DLL. It is this file that must be linked with doscalls.lib 
and dyn11.lib to create the application executable module. The data segment for this 
module is named data and the code segment is CSEG. In the figure three values are 
pushed to the stack: first, the data segment address for data; second, the offset 
address for msg1; and finally, the length of msgl is pushed. These values will 
eventually be accessed using a structure (template) and the stack starting address. 
During a push operation a variable is placed on the stack and then the stack pointer 
is decreased. Hence the stack loads as 


msgli | (lowest address) 
offset of msgl (next lower address) 
segment address of msgl (highest address) 


Following this loading of the stack a call to the DLL routine (dlink1) is made. 
The operating system automatically places a return address (4 bytes for a FAR call) 
on the stack in response to the call instruction. Figure 5.4 illustrates the called pro- 
cedure, dlink1, contained in the module dlinkl.asm. The first instruction of the 
called procedure saves the old (current) value of bp and sp now points to this saved 
copy of bp. Recognizing that the stack pointer is decreased following each push, the 
following stack values appear on the local stack: 


caller’s bp (lowest address) 
caller’s ip 

caller’s cs 

msgl | 

offset of msg] 

segment address of msg] (highest address) 


In the routine dlink1 the next instruction transfers the value in sp (which is the 
saved copy of the old bp’s address) to bp. The routine pushes ds (which points to 
the dynl.asm data segment) and loads the DLL routines’s data segment address into 
ds. The program can now access structures of the form specified by stl, which 
appears in the new data segment. This access takes the form 


variable.field 


where the fields specified for stl are m_len, m_offs, and m_seg. There are also three 
unnamed fields. Choosing variable equal to the address of the old bp, we can access 
the stack using the structure template. Hence the following values of interest can be 
retrieved by the DLL routine: 
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TITLE DLINK1 -- DLL routine for example #1 (dlinkl.asm) 


e 
’ 


extrn 


DESCRIPTION: This is the DLL routine for example #1. 


It is pre-loaded. 


-286C 
-sall 


VioWrtTTY: FAR 


dgroup GROUP data_dlll 


’ 
data_dll1l 


vio_hdl 


stl 


m_len 
m_ offs 
m_seg 
Sel 


data_dll1 


’ 
CODE1 


dlink1 


dlink1 
CODE1 


equ 0 


struc 

dw 

dw 

dw 

aw 

dw 

dw 

ENDS 

ENDS 


SEGMENT PARA PUBLIC 'CODE' 
CS: CODE1,DS:dgroup 


ASSUME 
PUBLIC dlinkl 
PROC FAR 


push bp 

mov bp,sp 

push ds 

mov ax,data_dlll 
mov ds,ax 


push [bp].m_seg 
push [bp].m_offs 
push [bp].m_len 
push vio_hdl 


call FAR ptr VioWrtTTY 


pop ds 
pop bp 
ret 
ENDP 
ENDS 
END 


SEGMENT PARA PUBLIC 'DATA' 


Figure 5.4 
[bp].m_len — length of msgl 
[bp].m_offs -— the offset of msgl 
[bp].m_seg — 


;Suppresses macro listings 


s;API routine 


;video handle 


;parameter structure 
;caller's bp 
;caller's ip 
;caller's cs 
;message length 
;message ptr offset 
;message ptr seg 


;caller's frame ptr 
;local stack 
;caller's ds 
;load new ds 


;use explicit parameter 
;values because locations 
;come from local stack 
;message seg address 
;message offset address 
;length message 

;video handle 


;d@irect API call 


’ 


;restore caller's data seg 


;restore frame pointer 


The called procedure, dlinkl, for the example of Figure 5.3. 


the segment address of msgl 


Chap. 5 


In dlink1 these values are pushed on the stack as well as the video handle and a 


FAR call to 


ViowrtTTy 


is made. Note that macro version is not used and the API service directly accessed. 
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Execution of these instructions results in the message “Dynamic Link Preloaded 
Routine” appearing on the screen with a line feed and carriage return. 

The routine dlink1 is a member of the DLL, dyn11.dll module created by the 
first link discussed above. This routine, dlinkl.obj, was linked with a routine 
dyninit.obj. What is this routine? Each DLL must have an initialization routine. For 
dyn11.dll the initialization routine is dyninit.obj and this routine appears in Figure 
5.5. This initialization routine simply writes the message “DLL Initialized” to the 
screen and forces the operating system to initialize the DLL. To ensure that the ini- 
tialization routine executes first the DLL entry point to the module’s procedure, init 
is specified as a parameter in the END pseudo-op: END init. Following initialization 
the routine must return a value of 1, not O, to the calling program. 


PAGE 40,132 
TITLE DYNINIT -- Initialization Routine for DLL-1 (dyninit.asm) 


DESCRIPTION: This routine is the initialization routine 
for the DLL dynil.dll. The routine merely prints a message. 


-286c 
-sall ;Suppresses macro listings 


xlist 
include sysmac.inc ;include API services 
-list 


dgroup GROUP init data ;defines automatic data seg 
init_data SEGMENT PARA PUBLIC 'DATA' 


initOK equ il ;OK return code 

msg db 'DLL Initialized',0ODH, OAH ;Initialization message 
msg_1l equ $-msg ;message length 

vio_hdl equ 0 ;Video handle 


init_data ENDS 


CINIT SEGMENT PARA PUBLIC 'CODE' 
ASSUME CS:CINIT,DS:dgroup 
init PROC FAR 


push bp ;save frame pointer 


@VioWrtTTY msg,msg_1,vio_hdl ;Write initialization msg 


mov ax,initOK ;OK return value 

pop bp ;restore frame pointer 
ret 

ENDP 

ENDS 

END init ;DLL entry point 


Figure 5.5 The initialization routine for the DLL called by the program in 
Figure 5.3. 
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Finally, Figure 5.6 presents the module definition file. This file is associated 
with the library dyn11.lib. Hence all references to segments and routines must come 
from dlinkl.asm and dyninit.asm. In this example these segments are preloaded, as 
specified in the definition file. Only dlink1 is exported because this is the only 
routine used by dyn1l.exe. Note that the presence of LIBRARY specifies that dyn11 


will be a DLL. 


LIBRARY 
PROTMODE 
DESCRIPTION 


SEGMENTS 


init_data 


CINIT 


data_dll1i 


CODE1 


EXPORTS 
dlinkl 


'Example #1 DLL' 


CLASS "DATA! 
PRELOAD 
CLASS 'DATA' 
PRELOAD 


Figure 5.6 The module definition file, dynll.def. 


Example 2. For this example, a load-on-call execution was prescribed for the 
DLL routines exported to the application. All routines remain the same as in Ex- 
ample 1 except the definition file, named dyn11.def. This file appears in Figure 5.7. 


LIBRARY 


PROTMODE 


DESCRIPTION 


SEGMENTS 


init_data 
CINIT 
data_dlll 
CODE1 


EXPORTS 
dlinkl 


‘Example #2 DLL' 


CLASS "DATA! 
LOADONCALL 
CLASS "DATA! 
LOADONCALL 


LOADONCALL 


LOADONCALL 


Figure 5.7 The module definition file, dyn22.def. 


It is important to note that the data segments (init_data, for the initialization routine, 
and data_dll1, for the DLL routine) in the DLL as well as the Code segments in the 
DLL are loaded as called based on the parameter LOADONCALL. 

The link and definition utilities are executed as follows: 
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link dyninit dlinkl, dyn22,,doscalls.lib,dyn22.def 
implib dyn22.1ib dyn22.def 


link dynl.obj, dynl.exe,,doscalls.lib dyn22.1ib,, 


These commands produced an executable module, dynl.exe, which accessed the 
dynamic link library, dyn22.dll, and imported the routine dlink1 only when actually 
called in the program dyn1.exe. In the earlier example access was granted immedi- 
ately because of the preload condition. Execution of dynl.exe produces the same 
result as it did in Example 1, but the DLL input occurred at load time rather than 
when linking takes place. Note that the message to the screen still reads 


“DLL Initialized 
Dynamic Link Preloaded Routine” 


even though the load-on-call status exists. This is because we have changed only the 
definition file to check this DLL implementation. 


Example 3. In this example we illustrate an example of run-time dynamic 
linking based on the OS/2 API services. Following the lead set by the first two 
examples, the routines dyninit.asm and dlinkl.asm were used to make up the DLL. 
Figure 5.8 illustrates the main calling module, dyn2.asm. 

The routine dyn2.asm uses the API service @DosLoadModule to load the 
DLL (DYN33.DLL) and it returns a handle to the DLL. To access entry points 
within DYN33.DLL the API services macro @DosGetProcAddr is called and an ad- 
dress returned for the entry DLINK1. This address is returned in addr_proc. Next the 
message parameters are pushed on the stack so that they can be accessed by 
DLINK1. A call is made via the CALL instruction and this writes msgl to the 
screen. Following release of the DLL using @DosFreeModule, the program exit 
takes place. Note that the two ASCIIZ strings corresponding to the DLL and the 
entry point name have uppercase letters. This is because the assembler always uses 
uppercase and both the API functions in dyn2.asm are case sensitive. The CALL 
instruction is not case sensitive; hence the references to dlinkl in dynl.asm are 
unaffected by whether the reference is to dlinkl or DLLNK1. In dyn2.asm the 
references must be upper case. 

Figure 5.9 illustrates the DLL definition file for Example 3. There are few 
changes in this file (DYN33.DEF) from earlier .def files. These three examples 
constitute the three ways in which dynamic link libraries can be implemented under 
OS/2. The examples all employed assembly language for both the calling module 
and the routines appearing in the DLL. The link sequence for Example 3 is as 
follows: 


link dyninit + dlinkl1,dyn33,,doscalls,dyn33.def 
implib dyn33.1lib dyn33.def 


link dyn2,dyn2,,doscallst+dyn33,, 
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PAGE 40,132 
TITLE DYN2 - Main calling program example #3 (dyn2.asm) 


DESCRIPTION: This program calls dyn33.dll to demonstrate 
explicit load by application assembler dynamic link libraries. 
The main calling routine is DYN2. 


-286c 
-sall ;Suppresses macro lists 


-xlist 
include sysmac.inc ;API services 
-list 


dgroup GROUP data ;defines automatic data seg 


STACK SEGMENT PARA STACK 'STACK'! stack defined 
dab 128 dup('STACK ) 
STACK ENDS 


’ 
data SEGMENT PARA PUBLIC 'DATA' 


msgl db ‘Dynamic Link Run-Time Routine',0ODH, OAH 
msg1_l equ $-msgl 

msg2 db 'Error on access DLL',ODH, 0AH 

msg2_l1 equ $-msg2 


action equ 0) ;code to end thread 
result dw (0) ;return code for error 
vio_hdl equ 0 ;video handle 


obj_buf dd 64 dup(?) ;error returm buffer 
obj _buf_len $-obj_buf ;length error buffer 
obj_buf_add obj_buf ;address buffer 
name_mod "DYN33',0 ;module name 

hhandle 0 shandle to DLL module 
name_proc '"DLINK1',0 ;DLL procedure name 
addr_proc 0 


’ 
data ENDS 


, 

CSEG SEGMENT PARA PUBLIC 'CODE' 
ASSUME cCS:CSEG,DS:dgroup 

DYN2 PROC FAR 


e 
’ 


@DosLoadModule obj_buf_add,obj_buf_len,name_mod,hhandle 
cmp ax,0 ;check for error 
jne ERROR 


@DosBeep 4000,200 


; 
@DosGetProcAddr hhandle,name_proc,addr_proc 
cmp ax,0 ;check for error 
jne ERROR 


@DosBeep 1000,500 

push ds ;push message segment 
lea bx,msgl ;offset of message 
push bx ;save offset 

push msgl1_l ;message length 


call addr_proc ;DLL routine to print msg 


e 
a 


Figure 5.8 Run-time dynamic linked library calling module. 
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@DosFreeModule hhandle 
cmp ax,0 ;check for error 
je EXIT 


@VioWrtTTY msg2,msg2_1,vio_hdl ;error message 


@DosExit action,result ;terminate all threads 
ENDP 

ENDS 

END DYN2 


Figure 5.8 (Concluded) 


LIBRARY dyn33 INITINSTANCE 
PROTMODE 

DATA NONSHARED 
DESCRIPTION 'Example #3 DLL' 


SEGMENTS 


init_data CLASS 'DATA' LOADONCALL 
CINIT LOADONCALL 

data_dll1l CLASS 'DATA' LOADONCALL 
CODE1 LOADONCALL 


HEAPSIZE 1024 


EXPORTS 
dlinkl 


Figure 5.9 The module definition file, dyn33.def. 


It is possible to access a DLL in an additional fashion: through specification 
of IMPORTS entry points in a module definition file. By listing the library entry 
points to be imported in a definition file for the application, the application can 
import DLL routines. 


5.3 OPTIMIZING THE C DESIGN PROCESS 


Most modern textbooks address the topics of structured programming, modular code, 
and top-down design. These techniques have come to embody an organized ap- 
proach to program development which is repeatable in an optimal sense. This 
approach is predictable and meaningful in that programmers of differing back- 
grounds will approach algorithm development in the same fashion when these tools 
are used. In the following discussion we explore each of these topics, starting with 
top-down design because it represents the start of the design process. 
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5.3.1 Top-Down Design, Structured Programming, 
and Modular Code 


Top-down design is an informal strategy for starting with a global problem statement 
and then subdividing the development into smaller and smaller modules until each 
module accomplishes a singular task. Such a systematic approach to design leads to 
modular techniques that develop and link program elements together to solve the 
overall task. 

A convenient starting point for the top-down approach is to define the func- 
tional structure for the program under consideration. This functional structure has 
been reflected in the Structure Charts of earlier programming examples. These charts 
illustrate a hierarchy of importance for the components of the program. Structure 
Charts are established by associating with level 0 an overall functional statement of 
the programming problem. This occupies a single box at the top of the hierarchy. 
Next, the level 1 position categories associated with variable I/O and algorithm 
computation are indicated at a reasonably high level. Below this level, successive 
reduction of the problem into multiple smaller pieces occurs, with the relationships 
clearly defined. Through this process the program architecture is defined in terms of 
hierarchy. The Structure Chart does not, however, illustrate the dynamic interrela- 
tionship among modular components. Also, it does not illustrate at the module level 
the flow of execution for the program. To achieve this, the top-down design proc- 
ess needs an additional mechanism for describing program activity. This mechanism 
can take one of two forms: the flowchart or pseudo-code, which describes the pro- 
gram activity in natural-language syntax. In this book we employ flowcharts for de- 
scribing programs dynamically. (The reader can just as conveniently approach pro- 
gram design using pseudo-code, but it is generally less compact than flowcharts, 
hence our use of the latter technique.) 

In general, the procedure discussed here is a reasonable approach to program 
design. The structure chart reflects the high-level functionalism and the flowcharts 
illustrate the more detailed dynamics at the module level. Top-down design is infor- 
mal and thus most useful for small-scale design tasks. When faced with larger de- 
sign problems, the programmer must resort to additional techniques to supplement 
the guidance obtained from the top-down methodology. We will consider two addi- 
tional tools, as discussed earlier: modular programming and structured code. 

The reader will note by now that in programs appearing in this book, there is 
a tendency to relegate many of the tasks to smaller functions and modules. This 
suggests the notion of modular programming. Modular programming concepts have 
been established over a long period of time during which theoretical methods 
evolved for designing programs [3,4]. The principal requirement on smaller program 
units or modules is that they be independently testable and can be integrated to ac- 
complish the overall program objective. 

Modules are generally defined, in the context of C programming, in terms of 
one or more related functions. Each function should perform a single independent 
task and be self-contained, with one exit and entry point. This suggests a single 
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“thread” to program execution, which is the manner in which most modern comput- 
ers execute code. Module execution in the world of the CPU is sequential. With this 
architecture in mind, it becomes straightforward to accept the one entry and one exit 
feature associated with functions, at least theoretically. 

We discussed global variables as a mechanism for returning more than one 
value from a function. When is this likely to become most necessary? One situation 
is the generation of an array of similar values. Here a single function might be used 
to compute a time series, for example, and each computation would generate an 
array element in recursive fashion. Obviously, the function should be self-contained 
and all array values generated at once. Consider the following function: 


filter (N) 
int WN; 
{ 
extern float y[]. x[]; /*x=time element*/ 
fioeat b, G 
int n; 
y[0]=0; /*Initialize*/ 
b=.01; 
c=.001; 


for (n=l; n<=N; n++) 
y(n]=c*y[n—1]+b*x[n]; 


} 


This low-pass filter generates a smoothing of the time series x[n]. The array y[n] is 
generated in its entirety with the simple one-statement for loop. It would be highly 
undesirable to fail to return the complete array from this function; hence the use of 
global variables is appropriate. This use does not detract from the modular nature of 
the function. Thus even though a module (or function) has one entry and one exit 
point, multiple values can be returned. 

Size is handled by accepting a general guideline that modules contain between 
10 and 100 lines of code. This is suggested as a rule of thumb and if, for example, 
the code were written in APL, 100 lines would be very tiresome to debug. For C, 
however, the guideline seems appropriate, as evidenced by the modules in this book. 
A more rigorous enforcement of size must resort to quantitative measures such as 
complexity and complexity metrics. Consider the metric [5] 


N = Nl + N2 (5.1) 
where 


N1 = total number of operators in a module 
N2 = total number of operands in a module 


Returning to the function filter, the following counts apply: 
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OPERATOR COUNT OPERAND COUNT 
as 6 y[O] Z 


(variable) 
Lt 24 


Here N is 35 [from Equation (5.1)]. What does this mean? To interpret N, a body 
of statistical data must evolve based on complex interactions between programmers 
and code. It is clear from this example that N = 35 is a reasonably simple program. 
In reference 6, a similar example with N = 28 is illustrated. Again, this metric value 
indicates a relatively small and understandable module. 


The programmer is unlikely to apply a complexity metric during program de- 


velopment. It is, nonetheless, useful to allow complexity to guide program develop- 
ment, particularly when modules begin to approach a high level of difficulty (for the 
programmer developing the code). Let us summarize some general guidelines on 
module development in C: 


1. 
Ze 


* 


Restrict modules to between 10 and 100 lines of code. 


Within the module concept, allow one entry and one exit (exception handling 
can call for multiple exits, but this is an abortive condition and the error state 
should be flagged before the exit). 


Arrays should be treated globally. 

Modules returning a single value should do so formally with return(). 
Modules returning multiple but small numbers of variables should do so with 
pointers (pointers are complex, so the trade-off here is how many pointers are 
involved). 

Modules returning large numbers of variables, other than arrays, should be 
rewritten. 

Modules returning an intermediate number of variables can do so with global 
declarations. 

A module should perform one self-contained task. 

Allow for exceptions to these guidelines when the code can be made easier to 
understand and it is not time-critical. 
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An example of point 9 would be where very simple “bookkeeping” is involved in 
a module for clarity and maintenance purposes. Also, the use of globals does not ap- 
preciably increase the level of difficulty of a small program but can significantly 
reduce the size of variable handling code (particularly when pointers are used as an 
alternative). 

The major difficulty with software development is not in determining how to 
make the computer function to execute a program but rather, in ensuring that a 
given program actually generates the output it was intended to generate. The empha- 
sis here is on software integrity, with the presumption made that the programmer 
will learn the mechanics of programming within a particular language. To simplify 
program design and development, structured programming techniques evolved. 
Dijkstra [7] defined the initial concept, and structured programming is now a well- 
established discipline which has greatly affected the C architecture. The notion of 
structured programming in the broadest sense encompasses top-down design and 
modular programming. At a more localized level, structured programming focuses on 
coding techniques intended to simplify program understanding and facilitate program 
use (such as program modification and maintenance). In the following discussion we 
focus on the latter area: structured code. 

The most desirable structure concept is sequentially defined code. In this 
instance instructions are executed as they are encountered. C provides for two 
deviations from this approach: conditional execution and iterative loops. We have 
seen examples of both of these conditions. Conditional execution included use of the 
forms 


1. if... 

2. il,else 

3. the conditional operator 
4. switch...case...break 


Similarly, iterative loops utilize the forms 


1. while... 
2. do...while 
Se 1Of 


These two groups of statements are the most important control mechanisms in the 
C language. They form the basis of C structured coding techniques. Although C 
allows the goto... statement, it is discouraged and appropriate only in very extenu- 
ating circumstances. It should be argued forcefully that any code segment using a 
goto can be rewritten to avoid this statement. The major difficulty with goto state- 
ments, as pointed out by Dijkstra, is that unrestrained branching within a module 
can take place. This can lead to difficulty in understanding the intent of the code. 

Structured code begins with a hierarchical description in the Structure Chart. 
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This artifact illustrates what functional activities are subordinate to other activities. 
At a glance, the user can glean overall functional program relationships from the 
program Structure Chart. This entity should be developed as the first component of 
program design. Next, the execution flow must be developed. The functional flow- 
chart serves as a convenient vehicle for accomplishing this. 

Briefly, there are a number of types of flowcharts. They vary from more 
functionally oriented descriptions of program behavior, in which generalized activ- 
ity is interconnected, to very detailed descriptions where each line of code literally 
occupies a place in the overall flowchart. In this book we favor the functional 
approach because it is a good compromise: It gives the user a sense of the program 
execution and does not require pages of description. 

As an alternative to the flowchart, pseudo-code can be used. Pseudo-code has 
the advantage that it is very close to the actual program mechanics and has the 
structure of natural language. With pseudo-code the uninitiated can develop a feel- 
ing for program execution while not fully comprehending the language syntax in 
which the program is written. A number of authors of high-level languages are de- 
veloping program design languages (PDLs) which are essentially pseudo-code. The 
PDL approach to program design is particularly appropriate for very large-scale 
program development that may require significant development time. In this case a 
need exists to have an easily understood design document that can be made avail- 
able to new programming team members. For most microcomputer applications, 
however, the flowchart is quite suitable. 

Actual module implementation within the confines of structured code employs 
sequential and control statements as discussed above. The module should have one 
entry and one exit path (with exception control handled so as to delineate the error 
condition). Finally, each module should be documented to explain its function and 
what data structures exist, where needed. The relationship of one module to another 
can be delineated in special cases where it is not explained in an associated flow- 
chart or Structure Chart. 

The purpose of this short discussion is to reemphasize the importance of struc- 
tured programming in the C language by briefly illustrating several features of the 
language. Also, we discuss some philosophical implications for structured code.We 
begin with the one entry and one exit precept applied to module definition. This 
control mechanism can be extended backward to the architectural structures men- 
tioned earlier. Next we discuss the implications of style and form. (Also, a brief 
look at templates is treated as part of style.) Finally, a general look at algorithm de- 
velopment is used to round out the discussion. Also, data structures are treated. 

The control and loop structures used in the C language are designed to provide 
one entry and one exit to modules. This ensures that control flow is linear through 
the structure (if, if...else, ..., while, do...while, etc.). Also, exit conditions are clearly 
made available to the user during execution. With regard to iterative structures such 
as loops, it is clear that multiple exits can be disastrous because the user may never 
learn about the state of the system that causes the exit condition. To jump outside 
a loop that is undergoing normal execution is highly undesirable. With conditional 
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structures the use of exception handling must be clarified. Consider the if... state- 
ment in the following form: 


if (check==0) 
{ 


printf ("Denominator zero"); 
exit(1); 
} 


Here the if statement specifically looks for an error condition and prints the message 
explaining this condition prior to exit. The exception handling is part of the if 
purpose. A sequence of the form 


for (n=l; n<=N; n+tt+) 


{ 
X=x+ta; 
if (x==NTOTAL) 
{ 
printf ("x max exceeded"); 
exit(1); 
} 
a=atb; 
} 


is less desirable because the causative factors (a, b, and x too large) are unclear at 
time of the exit. In general, we use the unconditional exit only [exit (1)] and we 
only use this exit when the complete nature of the error condition is absolutely clear. 
Also, it is used subject to the constraints indicated above. A typical use is 


if ((check=fopen (FN1,"r"))==NULL) 
{ 


printf ("Error on read file open"); 
exit(1); 
} 


To some extent this discussion is semantic. Exits from within loops should not 
occur. Since C does not allow branching or jumps (as in assembler, FORTRAN, and 
other languages), there is really no way to exit a loop except with an exception 
handler or a goto. We have virtually ruled out goto statements, so only exception 
handling remains. The latter exit should be avoided within a loop structure. Flag the 
condition and upon exit from the loop report all relevant parameter data prior to 
exit. The latter exit should be accomplished using a conditional structure that spe- 
cifically tests the exception status. 
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5.3.2 Templates, Style, and Form 


Style is a somewhat elusive feature of programming which reflects individual 
thought patterns as much as any organized approach to program development. 
Consider, for example, the problem of variable definition, mentioned earlier. The 
following is easily understood: 


mortgage int = loan_principal * interest_rate. 
What about the following? 


Instantaneous amp = exp(—time/delay factor) * 
/ cos(2. * pi * frequency * time) 


For technically inclined users, the following is much easier: 
A = exp(—t/tau) * cos(2. * pi * £ * t) 


(Those who are not technically trained probably will not care about such details.) 

Programmers with a background in FORTRAN, ALGOL, or original BASIC 
are familiar with restrictions on the length of a variable name. They tend to be more 
cryptic than programmers of more recent vintage, who are used to 32-character 
limits. This is decidedly a learned style feature. More important is the need to clar- 
ify variable meaning. If the programmer provides a design document, which is 
essential for a clear understanding of the program, each variable should be deline- 
ated in an unambiguous fashion. In cumbersome assignments, spelling out each 
variable name in a wordy fashion can often obscure the meaning of the underlying 
relationship. Similarly, by being too cryptic or obscure, the meaning of the equality 
can escape the reader. 

An additional feature of style is the nature of actual code reduction. In other 
words, is the code compact, or can each relationship be followed in easily readable 
form? The code 


if(((xl==cl) | (x2==+c2)) & ((x3==c3) | (x4==c4))) 
Al; 


is compact, the following is slightly easier to follow: 


if((xl==cl) | (x2==c2)) 
{ 
if((x3==c3) | (x4==c4)) 
{ 
Al; 
} 
} 


(If the reader has doubts as to which is easier, try assigning values and working out 
the truth table.) 
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As part of style we need to consider templates. This topic is meant to cover 
the overall program structure. A general template is as follows: 


Module 1 (main()) 


Documentation (comment describing module) 
Preprocessor (include files, define directions, globals) 
main() (function definition) 


Module 2 (function1(),...functionN()) 


Documentation (comment describing functions) 
functionl() 


functionN ( ) 


Module 3 (function(N+1)(),...functionM()) 
Documentation (comment describing functions) 


function(N+1)() 


functionM( ) 


Module L (functionQ(),...functionR()) 


Documentation (comment describing functions) 
functionQg( ) 


euneeionk() 
Here 
1<NKN+ iss «¢ «SMS ce SOs oe SR 
and 
253% oo eS 


Finally, we consider form. Good form consists of defining the optimum meth- 
odology for implementing an algorithm. Unfortunately, most algorithms are suffi- 
ciently complex that it is difficult to decide what the best way to implement the al- 
gorithm might be. The issue of form must be addressed in a somewhat simplistic 
fashion. Consider the following code fragment: 


for (n=1;n<=N;n++) 
{ 
for (m=1;m<=M;m++) 
{ 
v[nj=v[n]*v[n]; 
if((v[n]>q[m]) & (v[{n]<q[{m+1])) 
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increment++; 


Now consider the alternative 


for (n=1;n<=N;n++) 
{ 
v[nj=v[n]*v[n] 
for (m=1;m<=M;m++) 
{ 
if((v[n]>q{m]) & (v[{n]<q[m+1]) ) 
increment++: 


} 


The second form is admittedly more cumbersome, although easier to understand. 
What about time criticality? In the first fragment the expression 


v(n] = v[n]}*v[n] 


is executed NM times, while in the second fragment it executes only N times. The 
latter program fragment ensures an optimum time-critical compiled result. Although 
this example may appear academic, it is representative of the decisions regarding 
form that must be made. 

Algorithm development ‘The topic of this section is algorithms. Algorithms are 
structured approaches to solving mathematically, particular problems amenable to 
solutions. A more general definition would, of course, encompass most programming 
efforts. We have iterative and recursive programming and it is true that a fundamen- 
tal technique in designing efficient solutions is the recursive method, because this 
approach builds on an earlier solution. Table 5.2 illustrates some typical algorithms 
as discussed by Sedgewick [8]. We have already seen examples of some of these 
algorithm techniques. In general, we will not address the complete class of problems 
covered by the table; the interested reader is referred to reference 8 for a complete 
discussion. It is important, however, to recognize that algorithms are what computer 
programs are all about. Problems amenable to algorithmic solution can easily be 
tailored to computers. 

Data Structures We briefly consider the subject of data structures [9] (as opposed 
to file structures [10]). Table 5.3 illustrates some well-known data structures used in 
small- and large-scale program development. We have already seen arrays used as 
a basic element of the C language. Using the bitwise operators, it is possible to en- 
ter or extract information from data elements at the bit level. More complex data 
structures, such as hashed lists, heaps, linked lists, and priority queues, are special- 
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ized algorithms for handling large data organizations that require speed of access of 
optimized storage. Similarly, sparse array techniques minimize the amount of stor- 
age needed for multidimensional data. 


TABLE 5.2 SOME TYPICAL ALGORITHMS 


Type 
Mathematical 
Sorting 


Searching 
String processing 
Geometric 


Graph 


Advanced 


Comments 


Arithmetic, random numbers, interpolation, simultane- 
ous equations, integration 


Exchange, bubble, quicksort, radix, priority queues, 
selection/merging 


Sequential, binary, tree, hashing 

Pattern matching, parsing, file compression 

Polygons, line intersection, convex surfaces, grids, 
closest point 

Connectivity, mazes, shortest path, topological sorting, 
networks 

Systolic arrays, FFT, dynamic programming, linear 
programming 


All these techniques are used in developing the area of data structures and database 
design. The interested reader is referred to reference 9 for specific details of large- 
scale implementations. In this book we will confine most of the discussion to the 
primitive structures listed in the beginning of Table 5.3. 


TABLE 5.3 SOME REPRESENTATIVE DATA STRUCTURES 


Type 


Arrays 


Bit strings 


Bit maps 


Databases 


Comments 


These structures consist of concatenated variables 
stored in a block and accessible via one or more 
indexes. 


These structures constitute the basic building blocks 


of any language and are accessible in C by using 
the bitwise operators. 


This is a mapping of a set of variables and their 
associated parameters onto a set of bits, which 
constitutes a smaller set of storage. All attributes 
of the variables are not represented in this fashion, 
and the mapping must be attribute specific. 


Databases are complex data structures consisting of 
data items or fields collected into records that are 
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TABLE 5.3 (Concluded) 


Type Comments 


accessible either sequentially, randomly, or 
directly via indexes or keys. 

Hashing This is a structure technique in which an algorithm 
or function is used to generate an address of a 
data element from a key. Typical associated struc- 
tures would be a hash list. 

Heaps Heaps are most easily described as binary tree 
Structures possessing order and shape. Order, for 
example, might specify that the value at any node 
is less than or equal to the value at the children. 
Shape suggests the tree architecture. 

Linked lists These data structures are used as indexes to other 
Structures and have an associated pointer index 
that points to a relative record in the primary list. 


Priority queues This is a set of elements arranged according to 
priority. When an element is added or deleted, we 
do so in accordance with assigned priority or 
associated rules. 


Sparse arrays These are data structures with many zero elements. 
They can be reduced significantly to smaller 
Storage by using additional indexing arrays with 
an appropriate indexing algorithm. 


5.3.3 API Return Values and Error Checking 


When an API routine is called, it contains a return value in the AX register which 
is passed back to the calling routine. In general, if this AX or return value is zero, 
the call has been successful. If not, one of several possible error conditions may 
exist, depending on the value returned. The user has an option as to how to treat 
these calls. 

As an example of a typical API error return processing, consider 


error = DosGetPID(process IDs); 
if (error!=0) 


{ 


printf("Error on acquiring process ID”); 
exit(1); 
} 


The reader should feel free to insert his or her own error processing as appropriate 
following API service calls. 
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5.4 REEXAMINING THE CORE VERSUS PRESENTATION 
MANAGER API SERVICES 


The core or basic API services are largely derivative from the OS/2 Version 1.0, 
where only keyboard (Kbd), mouse (Mou), video (Vio), and DOS (Dos) calls are 
available. These are the only services treated in this book. For those readers famil- 
iar with Microsoft’s Windows environment, the PM presents a similar graphics-like 
interface. It is programmed in a fashion similar, but not identical, to Windows. Pro- 
gramming the PM requires a great deal of concentration and patience. This effort 
will be simplified greatly when additional object-oriented tools are developed. 
Petzold [11] has written a lengthy book on how to accomplish this Presentation 
Manager programming. The reader is cautioned that some differences exist between 
the PM described in Petzold’s book, which is based on the Microsoft version, and 
the IBM version of the Presentation Manager, which was released after the Micro- 
soft version. When accessing the graphical interface, for example, in the full com- 
mand screen mode the Vio calls must be used. Under PM the Gpi function calls are 
used. 


5.5 ADVANCED C EXAMPLE: A THREE-DIMENSIONAL SURFACE 


In this section we present an analytical approach for describing three-dimensional 
surfaces within the framework of simple vector arithmetic. A technique for remov- 
ing “hidden lines” is illustrated based on consideration of the rotating characteristics 
of facets. Here a facet is a member of a logical subdivision of the three-dimensional 
surface. We begin with a brief discussion of surface characterization. 


Functions of Two Variables 
It is convenient to denote a function of one variable using the notation 


y = fix) (5.2) 
Graphically, such a relationship is represented with a two-dimensional plot using the 
independent variable, x, along the horizontal axis and the dependent variable, y, 
along the vertical axis. When a function depends on two variables it is representable 
in a three-dimensional space defined by 


z = fix, y) (5.3) 
In displaying such data a third axis must somehow be represented on a two-dimen- 
sional surface, the display screen. We have seen that it is useful to assume three 
perpendicular (orthogonal) axes: an x-axis, a y-axis, and a z-axis. Points in this space 
are denoted by 
(% ¥,Z) = OY, f% Y)) (3.4) 
The geometry for a three-dimensional surface consists of a grid of x-y points. 


15 Ho Ope Me, 2, vey ING Pat se Dy 2, sey VE} 
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Here the sets {x,} and {y,} have been chosen to span the space of interest. The 
three—dimensional surface is then determined relative to this grid using Equation 
(5.3). We assume further that an observer is located at the point (x,, y,, z,) which is 
achieved by a rotation (a, B, y) about the x, y, and z axes, respectively. (Note that 
this rotation is not composed of orthogonal components.) This rotation was treated 
in some detail in Chapter 4 and the reader is referred to the routine rotmat() and 
rotpt() for a complete discussion. 

With this formulation, then, we can generate an abstract three-dimensional 
space with the observer located at any point in the space. Following the rotation a 
new set of coordinates is defined by 


Xx X 


a = ROBY) 1 Yn, (3.5) 
F(X > Yin) FX» Yn) 


R(a, B, y) is given by Table 4.1. To display this space it will be useful to collapse 
the x-axis once a suitable rotation has been achieved. The points plotted on this 
display will then be members of the set 


{(O, y', f(x’, y',)): n=1,2,....N; m=1,2,...,.M} 


The order for the display will be to let {y' } correspond to column positions and 
{f(x',, y'_,)} correspond to row positions. 

One final concept is needed: the notion of a facet. Basically, for plotting 
purposes it is useful to break the surface into facets (or small localized areas). The 
methodology for achieving this (used here) is to consider a grid structure on the x-y 
plane and assume a facet to be bounded by each set of grid lines projected onto the 
surface. For example, if we consider a surface grid, it is clear that the four x-y plane 
grid points 


i Xs Vs 0) 

2 ,¥,0) 

3: (Xv yma 0) 
4: Xp by n? 0) 


define the locations of the vertices of the grid. Lines connecting 1 and 2, 2 and 3, 
3 and 4, and 4 and 1, respectively, define the grid. Projecting these lines onto the 
surface yields the surface points 


(X,, x nm? fi (X,» y n)) 
(x, J mae? IX,» yao) 
ap Ye? Comer Viner) 


(Xp Lap Caer Yn) 


oe ae oe 
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Connecting these points cyclically yields the surface facet. When collapsed along the 
x-axis we have the final points 


1: (0, ¥,.f%,)¥,,)) 

2: (95 Vin AE,» nerd) 
3: (0, Y ge Ina Vicia) 
4 (0; Yi AE nu Ynd) 


If these points are plotted with the y-axis corresponding to column values and 
the z-axis corresponding to row values, a surface representation will be displayed 
with facets outlined. 

It is important to recognize that the surface described above will display all 
lines appearing in the facets. This includes “hidden lines,” which are those lines 
appearing in facets whose view would normally be obstructed. This obstruction re- 
sults from the fact that other facets are located in front of the facet in question when 
viewed in the chosen direction. 

To avoid illustrating hidden lines, it is useful to delete plotting of facets con- 
taining these lines. Although there are several ways to eliminate these hidden line 
facets, a very simple procedure is to create a vector normal to the facet and ignore 
the facet if this vector has a negative component pointing into the screen. Since the 
x-axis is normal to the screen, this implies that a negative, x-component of this 
normal vector would denote a facet with hidden lines. 

We can create this normal vector from any three points in the surface. Suppose 
that we have the vertices defined by vectors from the origin: 


P, ao (x,, yp z,) 
Pp, = an Yo Z,) (5.6) 
P; = (55 Y55 2,) 


and cyclically define line segments 


ml, a (p, -_ P,) 
m,= (P,- P,) (3.7) 
m, aa p= P,) 
Then a normal to the surface subtended by these three line segments is given by 
n=m,xm,, (=1, 2, 3) (O30) 


In this equation i is cyclic (modulo 3). The vector product is defined by the deter- 
minant 


ve SN x™ 
i j k 

n= |m, m,, m,, (5.9) 
m m m 


(i+ 1)x (i+ 1)y (i+1)z 
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where the first row consists of Cartesian unit vectors. Since it is the x-axis term we 
are interested in, we examine 


Nn, - He acy - Pi TT ya, (5.10) 
Here 
ran Pas Pan 
m=m itm, j+mk (5.11) 
If 
n.< 0 (3,52) 


the facet contains hidden lines. 


A Simple Mathematical Example 


It is useful to create a simple example to illustrate a three-dimensional surface. 
Consider the function 


z = A? (5.13) 


[(z IN)\}x +y / 


This function has the familiar (sin x/x)* behavior. We note that in the limit (x, y) 
= (0, O) the result is 


z= A’ (5.14) 
It is useful to generate values for x and y in the range [-10.,10.] with N = an input 


value that is a measure of the range of z. 
Figure 5.10 illustrates the MAKE file for a program gen3d.c, which creates 


gen3d.obj: gen3d.c 
cl -c -Zi gen3d.c 


xadiskw.obj: xadiskw.c 
cl -c -Zi xadiskw.c 


gen3d.exe: gen3d.obj xadiskw.obj 
link gen3d.obj+xadiskw.obj,,,, 


Figure 5.10 The MAKE file for the program 
that writes the data file for a three-dimensional 
(sin x /x)* surface. 


this surface data file. Figure 5.11 illustrates a main calling program that generates 
these values and writes them to disk. Initially, the total number of values (x, y, z) for 
each point on an x-y grid spaced at unity intervals in the range above, is written to 
disk followed by the points themselves in x, y, z order. This is an array and is 
defined as specified above. It is the array xarray[] in Figure 5.11. Figure 5.12 illus- 
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/* generate 3d surface */ 
#include <math.h> 
float xarray[2000],x[500],y[500],z[500]; 


main() 
{ 
int n,m,ncount = 21,mcount = 21,m1,m2,N,NN; 
float A= 10., error = 1.e-5; 
double PI = 3.141592654,u,v; 


printf("Input interval divider\n") ; 
scanf("%d", &NN) ; 


m2 = 1; 
ml = 1; 

for(n = l;n <= ncount;n++) 

{ 

for(m = 1l;m <= mcount;m++) 


{ 


x{m2] = (float) (m - mcount + 10); 
y({m2]) = (float) (n - ncount + 10); 

u (double) (x[m2]); 

Vv (double) (y[m2]); 

u (double) ((PI/NN) *sqrt(u*u + v*v)); 


if((u < error) && (u > -error) ) 
z([m2] = A; 

else 
z(m2] = A*(sin(u)/u) ; 


z2(m2] = z2[(m2)*z[m2]; 
xarray[ml] = x[m2]; 
xarray[ml+1] = y[m2]; 
Xarray[ml1+2] z(m2]; 
m2++; 
ml = ml + 3; 
} 
} 
N = nl-1; 
xarray_diskwt(N); 


} 


Figure 5.11 The program gen3d.c, which generates the surface data file. 


trates the disk write function. Figure 5.13 contains the MAKE file for the program 
that plots the three-dimensional surface. 

Figure 5.14 presents a main calling function for the program that plots the 
three-dimensional surface input using xarray_diskrd(), which is contained in Figure 
5.15. The function threeD_graph() reads rotation angles for locating the observer and 
rotates the input points. These functions, rotmat() and rotpt(), have been mentioned 
previously. Next, the data is scaled using scale(), which appears in Figure 5.16. The 
function scale() simply ensures that all x, y, and z values lie within the interval 
boLagdcals 

After scaling the data, threeD_graph() clears the screen, sets CGA display 
mode, and plots the facets using threeD_facet(). This function appears in Figure 
5.17. The routine threeD_facet() first loads the arrays xa[], ya[], and za[] with each 
of the four vertex points on the facet. A check for a hidden-line condition is made, 
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/* Function to write xarray to disk */ 


#include <stdio.h> 


xarray_diskwt (NCOUNT) 
int NCOUNT; /* Number points */ 
{ 
int n,check; 
FILE *outfile; 
char FN1[81]; 
extern float xarray[]; 


printf("Input database filename\n") ; 
gets(FN1); 
gets (FN1); 


if((outfile = fopen(FN1,"w")) == NULL) 
{ 
printf("Output file failure "); 
exit(1)>; 


} 
fprintf(outfile,"%d \n",NCOUNT) ; 
for(n = 1;n <= NCOUNT;n++) 
fprintf (outfile,"%£ \n",xarray[(n]) +; 
if((check = fclose(outfile)) != 0) 
{ 
printf("Error on output file close"); 
exit(1); 
} 


Figure 5.12 The file xadiskw.c, which generates a Protected Mode disk write 
using reentrant library routines. 


mmain3d.obj: mmain3d.c 
cl -c -Zi mmain3d.c 


facet3d.obj: facet3d.c 
cl -c -Zi facet3d.c 


xscale.obj: xscale.c 
cl -c -Zi xscale.c 


rotmat.obj: rotmat.c 
cl -c -Zi rotmat.c 


rotpt..0bj]* rotpt.c 
cl -c -Zi rotpt.c 


xadiskr.obj: xadiskr.c 
cl -c -Zi xadiskr.c 


pprtscr.obj: pprtscr.c 
cl -c -Zi pprtscr.c 


mmain3d.exe: mmain3d.obj xscale.obj facet3d.obj pprtscr.obj\ 
rotmat.obj rotpt.obj xadiskr.obj cgraph.lib 
link /CO mmain3d+xscale+facet3d+rotmat+rotpt+pprtscr+\ 
xadiskr,,,Ccgraph,, 


Figure 5.13. The MAKE file for the program that plots a three-dimensional 
surface based on an input data file. 


Sec. 5.5 


#define INCL_BASE 
#include <os2.h> 


Advanced C Example: A Three-Dimensional Surface 


This routine sets & clears CGA mode with screen clear--mmain3d.c 
The generalized nomenclature is used. 

A 3D (sin(u)/u)**2 is plotted. 

The routine calls gphrout.c graphics functions. */ 


Conditional load */ 
OS2 includes */ 


#include <stdio.h> 


struct _STRINGINBUF lkbd_buf; 
CHAR kbd_buf[80]; 


UINT action = 0; 
UINT error_code = 0; 
UINT wait = 1; 


CHAR dstat[1]; 
CHAR dstatl1[1]; 


float xarray[3072],scalex,scaley,scalez,x,y,z,a[10]; 
int ncount,mcount, count; 


keyboard buf len */ 
keyboard buffer */ 


end thread */ 
result code */ 
reserved word */ 


lock status */ 
lock status */ 


needed globals */ 
x-y count max */ 


se 
raster line array */ 
MM[4] = (0x40,0x10,0x04,0x01}; byte mask */ 
w[8] = {128,64,32,16,8,4,2,1}; gross weight */ 
s[4];? dummy */ 

shift1[4] = ({6,4,2,0}; byte pos. shift */ 
in_buffer1[4] {0x1B,0x4B,64,1}; location byte */ 
in_buffer2[2] {Ox0D,0x0A}; e.r & Lat. *7 
in_buffer3[3] {0x1B,0x41,8}; escape sequence */ 
in_buffer4[2] {Ox1B,0x32}; line spacing */ 
dev name[S] = {*L','Pt, "Fr, *2*, 


col1[320]; 


extern prtscr(); PrtScr routine */ 


SHANDLE vio_hdl = 

SHANDLE kbd_hdl = 0; 

UINT wait2 = 1,nnn; 

UINT xb = 75,xe = 150,yb = 25,ye = 175; 
SEL MM1; 

int n,m,m1,N,nm_count; 

float alpha0O,beta0,gamma0; 


video handle */ 
keyboard handle */ 
reserved */ 

box points */ 
selector */ 

plot variables */ 
direction cosines */ 


struct _VIOPHYSBUF PVBPrt2; 
struct _VIOMODEINFO CGAm; 
struct _VIOMODEINFO STDm; 


physical buffer */ 
CGA structure */ 
80 x 25 struct */ 


PVBPrt2.pBuf = (BYTE far *) (OxB8000) ; 
PVBPrt2.cb = 0x4000; 


buffer start */ 
buffer size */ 


CGAm.cb = 12; 
CGAm.fbType = 7; 
CGAm.color = 2; 


struct length */ 
CGA mode */ 
CGA color */ 


Figure 5.14 The program mmain3d.c, which is the main 
plotting and printing the three-dimensional surface. 


CGAm.col = 40; 
CGAm.row = 25; 
CGAm. hres 320; 
CGAm.vres 200; 


STDm.cb = 12; 
STDm.fbType = 1; 
STDm.color = 4; 
STDm.col = 80; 
STDm.row = 25; 
STDm.hres = 720; 
STDm.vres = 400; 


text columns */ 
text rows */ 

CGA hor res */ 
CGA vert res */ 


struct length */ 
80 x 25 mode */ 
STD color */ 
text columns */ 
text rows */ 

STD hor res */ 
STD vert res */ 


calling program for 
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buffer size */ 


printf("Input ncount\n") ; 
scanf ("%d", &ncount) ; 
Printf("\n Square array: ncount=mcount\n") ; 


X-axis count */ 


mcount=ncount ; /* y-xais count */ 
count=ncount; /* grid shift */ 

/* Input rotations */ 
printf("Input x-rotation (rad)\n"); /* x-rotation */ 
scanf("%f", &alpha0O) ; 
printf("Input y-rotation (rad) \n") ; /* y-rotation */ 
scanf("%f", &beta0) ; 
printf("Input z-rotation (rad) \n") ; /* z-rotation */ 


scanf("%f", &gamma0) ; 


rot_mat(alpha0,beta0,gamma0) ; loads global a[] */ 
N = xarray_ diskrd(); /* disk values */ 


ml = 1; 
for(n = 1l;n <= ncount;nt++) 
{ 
for(m = 1;m <= mcount;mt++) 


{ 


/* ist facet group */ 


xX = xarray[ml]; /* x-input rotation */ 
y = xarray[mit+l1]; /* y-input rotation */ 
Z = xXarray[ml1+2]; /* z-input rotation */ 
rot_point() ; /* rotate (x,y,z) */ 
xarray[ml] = x; /* reload x */ 
xarray[ml+l1] = y; /* reload y */ 


xarray([m1+2] Z? /* reload z */ 
ml = ml + 3; /* inc index 3 */ 


scale(); X,Y e-> [1,—1] */ 


set CGA mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &CGAm) ,vio_hdl) ; 


cclsCGA(vio_hdl); /* clear CGA screen */ 


VioScrLock(wait2, (char far *)dstatl,vio_hdl); /* lock screen */ 


/* physical buffer */ 
VioGetPhysBut((struct _VIOPHYSBUF far *)&PVBPrt2,vio_hdl)j; 


MM1 = PVBPrt2.asel[0]; /* selector */ 


ml = 1; 
nm_count = 3*ncount*mcount - (ncount*3 + 6); /* adjust limit */ 
for(n = 1l;n <= ncount;n++) 

{ 
for(m = 1;m <= mcount;m++t) 


{ 


if(ml < nm_count) /* check facet count */ 
threeD facets(m1,MM1) ; /* plot facets */ 
ml = ml + 3; /* increment index */ 


} 
} 


prtscr (MM1) ; 


/* 


VioScrUnLock(vio_hdl) ; /* unlock screen */ 
/* hesitate screen */ 


PrtSc routine */ 


KbdStringIn((char far *)kbd_ buf, 
((struct _STRINGINBUF far *) &lkbd_buf), 
wait,kbd_hdl); 


Figure 5.14 (Continued) 
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} 


c1rCGA (MMM) 
SEL MMM; 
{ 
INT n; 
INT N1 = OXx1F3F; end odd buffer */ 
INT DM = 0x2000; even offset */ 
PCHAR ptr; pointer scr buf */ 


for(n = O;n <= N1;n+t+) 
{ 
ptr = MAKEP(MMM,n) ; odd far pointer */ 
*ptr = 0; clear odd buffer */ 
} 

for(n = O;n <= Nl1;n++) 
{ 
ptr = MAKEP(MMM, DM+n) ; even far pointer */ 
*ptr = 0; clear even buffer */ 


) 


/* Function to read xarray from disk 
#include <stdio.h> 
xarray_diskrd() 


extern float xarray[]; 
int n,check,counter; 
FILE *infile; 

char FN2[81]; 


printf("Input read database filename \n") ; 
gets(FN2); 
gets (FN2) ; 


if((infile = fopen(FN2,"r")) == NULL) 
{ 
printf("Input file failure"); 
exit(1); 
} 
fscanf(infile,"%d \n",&counter) ; 
for(n = 1;n <= counter;n++) 
fscanf(infile,"*sf \n",&xarray[n]); 
if((check = fclose(infile)) != 0) 
{ 
printf("Error on input file close") ; 
exit(1); 


return(counter) ; 
} 


/* set STD mode */ 
VioSetMode(((struct _VIOMODEINFO far *) &STDm) ,vio_hdl) ; 


DosExit(action,error_code) ; 


} 


cclsCGA(vio_hdl11) 
SHANDLE vio_hdli; 
{ 
SEL MM; 
UINT waitl = 1; 
struct _VIOPHYSBUF PVBPrtl1; physical buffer */ 


PVBPrti.pBuf = (BYTE far *) (OxB8000) ; phys buf start */ 
PVBPrtl.cb = 0x4000; buffer length */ 


VioScrLock(waitl1, (char far *)dstat,vio_hdll1l); lock screen */ 
physical buffer */ 


Figure 5.14 (Continued) 
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VioGetPhysBuf((struct _VIOPHYSBUF far *) &PVBPrt1,vio_hdll) ; 


PVBPrtl1.asel[0]; /* selector */ 
clrCGA (MM) ; /* CGA clear */ 


VioScrUnLock(vio_hdl1) ; /* unlock screen */ 


Figure 5.14 (Concluded) 


/* Function to read xarray from disk */ 
#include <stdio.h> 
xarray_ diskrd() 


extern float xarray[]; 
int n,check, counter; 
FILE *infile; 

char FN2[81]; 


printf("Input read database filename \n") ; 
gets (FN2) ; 
gets (FN2) ; 


if((infile = fopen(FN2,"r")) == NULL) 
{ 
printf("Input file failure") ; 
exit(1); 


fscanf(infile,"%d \n",&counter) ; 
for(n = l;n <= counter;n++) 
fscanf(infile,"%f \n",&xarray[n]); 
if((check = fclose(infile)) != 0) 
{ 
printf("Error on input file close") ; 
exit(1); 
} 


return(counter) ; 


} 


Figure 5.15 The file xadiskr.c, for reading the disk file input to the surface 
plotting program. 


and if the facet is to be plotted, further scaling from [—1.,1.] to screen coordinates 
is implemented. Here only the y-z plane is considered (the x-axis is collapsed). 
Figure 5.18 contains the file gphrout.c used as a basis for the library 
cgraph.lib. These routines are called to access the screen buffer. Figure 5.19 illus- 
trates the output with a = y = 0 (no rotation about the x and z axes). In this figure 
B= 0.8, which is a counterclockwise rotation of 0.8 radian about the y-axis. Effec- 
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/* Function to scale xarray data */ 


261 


#include <stdio.h> 


scale() 


{ 


extern int ncount,mcount; 
extern float xarray[],scalex,scaley,scalez; 


int n, 


float 
float 


ml = 
for(n 


{ 


m,ml1; 


max_xX -1.e14,max_y = -1.e14,max_ -1.e14; 


min_x = 1.e14,min_y = 1.e14,min_z = 1.e14; 


1; 


= ljn <= ncount;n++) 


for(m = 1l;m <= mcount;m++) 


} 


scalex 


/* max/min determine */ 

if (max_x 
max_x 

if (min_x 
min_x 

if (max_y 
max_y 
if(min_y 
min_y 

if (max_z 
max_Z 


xarray([m1]) 
xarray([ml1]; 
xarray([ml1]) 
xarray([ml1]; 
xarray([ml1+1]}) 
xarray([ml1+1]; 
xarray[ml1+1]) 
xarray[ml1+1]; 
xarray([ml1+2]) 
xarray([m1+2]; 
if(min_z xarray(ml1+2]); 
min_z xarray[m1+2]; 
ml = ml + 3; /* next point set */ 


) 


IvitAIvVvtAHIV IA 


/* scale [-1,1] */ 
(max_xX - min_x); 


2./ 
scaley 2./(max_y - min_y); 
2sf 


scalez 
1; 


ml = 
for(n 


{ 


(max_z - min_Z); 


= l7n <= ncount;nt+) 


for(m = 1;m <= mcount;m++) 


{ /* normalize [1,-1] */ 
xarray[ml]) = -1. + scalex*(xarray[ml] - min_x); 

xarray[ml+1] = -1l. + scaley*(xarray[ml+1] - min_y); 

xarray[m1+2] = -1. + scalez*(xarray[m1l+2] - min_z); 


m1 + 3; 


Figure 5.16 The file xscale.c, used for scaling the array between (-1,+1) along 
all three axes. 


tively, this tilts the viewing angle upward so that the observer is looking down at an 
angle toward the image. Figures 5.20 through 5.22 maintain a and y at zero but 
change £ to span 1.0, 1.2, and 1.4 radians, respectively. This progressively tilts the 
image toward the reader, as illustrated. Figure 5.23 presents the figure for a = y = 
O and 6 = 1.0 with N = 12 instead of N = 7 [see Equation (5.13)]. 
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/* Function to plot 3D facets: coordinates for CGA -- facet3d.c*/ 


#define INCL_BASE 
#include <os2.h> 
#include <stdio.h> 


threeD facets (m1,MM1) 
int m1; /* index */ 
SEL MM1; 
{ 
extern int count; 
extern float xarray[],x,y,z,scaley = 125.,scalez = 
float z21,22,y1,y2; 
int n,ne? 
float z_start = 25.,y_start = 25.,z mid = 75.,y_mid = 125.; 
float dyl,dy2,dz1,dz2,xa[5],ya[5],za[5]; 


ne = 3*count; /* next y-value */ 
xa[1] xarray[ml]; /* 1st y-value grid */ 
ya[1] xarray[ml1+1]; 

za[1] xarray[ml1+2]; 

xa[2] xarray[ml1t+3]; 

ya[2] xarray([m1+4]; 

za[2] xarray[m1+5]; 


xa[3] 
ya[3] 
za[3] 
xa[4] 
ya[4] 
za[4] 


xarray [ml+nct+3]; 2nd y-value grid */ 
xarray [mlt+nct4]; 

Xarray[mlt+nct5]; 

Xarray[mlt+nc]; 

xarray [mlt+nct1]); 

xarray [ml+nct2]; 


dyl va(17; ck rotation 
dy2 ya[2]; 
dzl1 za[1]; 
dz2 za[2]; 
if ((dy1*dz2 dzl*dy2) > 0) 
{ 
for(n = lj;n <= 4;n++) /*® scale facet 
{ 
za([n] = z_start + (z_mid - za[(n]*scalez) ; 
ya(n] = y_start + (y_ mid + ya[n]*scaley) ; 


lin <= 3;n++) /* plot 3 of 4 


ya[n]; 
ya(nt+1]; 
za[n]? 
za(n+1]; 


pltpt(y1,y2,21,22,MM1) ; collapsed y-z */ 


ya[4]; 

ya[1]; 

za[4]; 

za[1]); 

pltpt(y1,y2,21,22,MM1) ; /* 4th segment */ 
} 


tou w tn 


Figure 5.17 The file facet3d.c, used to generate the individual surface facets. 
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/* Graph routines Protected Mode--gphrout.c */ 


#define INCL_BASE 
#include <os2.h> 


bboxx (xb, xe, yb, ye,MM1) 
UINT xb,xe,yb,ye; 


SEL MM1; 

{ 

lineh(yb,xb,xe,MM1) ; /* top line */ 
lineh(ye,xb,xe,MM1) ; /* bottom line */ 
linev (xb, yb, ye,MM1) ; /* right line */ 
linev (xe, yb,ye,MM1) ; /* left line */ 


} 
lineh(y,x1,x2,MM1) 
UINT y,x1,x2; 
SEL MM1; 
{ 
UINT n; 
for(n = xl;n <= x2;n++) 
wdot(n,y,MM1) ; /* hor line */ 


} 
linev(x,y1,y2,MM1) 
UINT x,yl,y2; 
SEL MM1; 
{ 
UINT n; 
for(n = yly;n <= y2;n++t) 
wdot (x,n,MM1) ; /* vertical line */ 


} 
wdot (x, y,MM1) 
UINT x,y? 
SEL MM1; /* x=col,y=row */ 
{ 
PCHAR ptr; 
UINT DM = 0x0000; 
CHAR MASK1 = 0x01; /*® set dot */ 


if(y & 0x01) 

DM = 0x2000; /* even buffer */ 
ptr = MAKEP(MM1,DM+(80*(y >> 1) + (x >> 2)))? /* dot location */ 
*ptr =(*ptr | (MASK1 << (2*(3 - x % 4)))); /* "OR" dot */ 


} 
uwdot (x, y,MM1) 
UINT x,y; 
SEL MM1; 
{ 
PCHAR ptr; 
UINT DM = 0x0000; 
CHAR MASK1 = 0x00; /* clear dot */ 


if(y & 0x01) 

DM = 0x2000; /* even buffer */ 
ptr = MAKEP(MM1,DM+(80*(y >> 1) + (x >> 2)))? /* dot location */ 
*ptr = (MASK1 << (2*(3 - x % 4))); /* write undot */ 
} 

pltpt(x1,x2,y1,y2,MM1) 
float x1,x2,y1,y2; 
SEL MM1; 
{ 
float m; /* slope */ 
int row; 
int col; 


Figure 5.18 The file gphrout.c, containing the expanded line plot routines (and 
the line unplot routines). 
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if (xl X2) 


1000.; /* 


/*® 


else 
m= (y2-yl1)/(x2-x1); 
if( x2 > x1) 
for(col = (int) (x1)+1;col <= (int) (x2) ;col++) 
{ 
row =(int) (yl + m*(col - x1)); 
wdot (col, row, MM1) ; 
} 


/* 
/* 


} 


else 


{ 
Lf (x2 < x1) 


{ 
for(col =(int) (x2)+1;col <= (int) (x1) ;col++) 


row=(int) (y2 + m*(col - x2)); 
wdot (col, row, MM1) ; 
} 


/* 
} 


else 
{ 
col = (int) (x1); 
if(yl > y2) 


/* 


for (row=(int) (y2)+l;row <= 
wdot(col,row,MM1) ; 
} 
else 
{ 
for (row=(int) (yl)+l;row <= 
wdot(col,row,MM1) ; 
} 


} 


upltpt(x1,x2,y1,y2,MM1) 
float x1,X2,V71,y27 
SEL MM1; 


{ 
float m; 
int row; 
int col; 
if(xl == 
n= 
else 
m= (y2-yl1)/(x2-x1); 
if(x2 > x1) 


X2) 
1000.; 


for(col = (int) (x1) ;col <= (int) (x2) ;col++) 


row = (int) (yl + m*(col - x1)); 
uwdot (col, row,MM1) ; 
} 
} 
else 
{ 
L£ (x2 < x1) 


for(col = 


row=(int) (y2 + m*(col -x2)); 


Figure 5.18 (Continued) 


(int) (x2)+1l;col <= (int) (x1) ;col++) 
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zero divide */ 


normal slope */ 


line equation */ 
write dot */ 


write dot */ 


verticle line */ 


(int) (yl) ;row++) 


(int) (y2) ;row++) 


slope */ 


zero divide */ 


normal slope */ 


line segment */ 
erase dot */ 


Sec. 5.5 
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uwdot (col, row,MM1) ; 
} 


} 
else 
{ 
col = (int) (x1); 
if(yl > y2) 
{ 


for (row=(int) (y2)+l;row <= 
uwdot (col, row, MM1) ; 
} 


else 


for (row=(int) (yl)+l;row <= 
uwdot(col,row,MM1) ; 


Dimensional Surface 


/* erase dot */ 


(int) (yl) ;row++) 
/* erase dot */ 


(int) (y2) ;row++) 
/* erase dot */ 


Figure 5.18 (Concluded) 
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5.6 SUMMARY 


This chapter has provided an examination of additional basic OS/2 features within 
the core API and has reinforced programming techniques within the C language, the 
primary language of choice for programming the Presentation Manager as well as 
more complex activities under OS/2. We began with a look at mixed-language pro- 
gramming in the context of C and assembler. Next, dynamic linked libraries were 
investigated from the viewpoint of assembly language, where they are more clearly 
understood. The use of load-time DLLs is recommended when memory allocation is 
to be optimized and a set of routines is to be called on a frequent basis. Load-time 
dynamic linking has the advantage that the calling routine does not need to ascer- 
tain the location of the module at loading. Run-time dynamic linking is recom- 
mended for those applications where memory allocation is dynamic and at a pre- 
mium and the routines to be accessed are done so infrequently. This technique 
requires access through API service calls. 

The C design process was examined from the viewpoint of top-down design, 
structured programming, and modular code. Recommendations were provided regard- 
ing module size and implementation. A typical template for C design was presented 
and the difficult issues of style and form touched upon. Style is such a crucial factor 
in the development of maintainable code that it is very surprising how often it is 
overlooked. Similarly, form can mean the difference between code that runs, and 
code that purports to accomplish the job but is so cumbersome and slow that it fails 
to achieve its objectives within a reasonable length of time. 

All the API services return values that depend on the outcome of the call. The 
question of whether or not a program should monitor those outcomes, once the 
original debugging is complete, was left to the reader. Frequently, in the interest of 
brevity, the full API return checking has been suppressed in this book unless a 
hardware failure can result, such as the inability to access a disk. 

A reexamination of the basic API core services was referenced: the Kbd, Mou, 
Vio, and Dos services. These are the Version 1.0 services and have since been 
added to by the presence of the PM functions, although these PM services are not 
treated in this book. Finally, a C application was developed. This application con- 
sisted of the plotting of a three-dimensional surface in the CGA mode of the OS/2 
command screen mode. The purpose of the presentation was to illustrate the man- 
ner in which moderately large-scale programs would be interfaced to OS/2 in the 
normal operational environment, with a particular emphasis on the techniques out- 
lined earlier in the chapter, such as modular code development. 
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PROBLEMS 


If a routine is self-contained within a task and called very infrequently, what OS/2 
technique could be used to conserve storage? 


What sequence of steps differentiates a DLL from another executable module? 

In Figure 5.2, what is the parameter on the stack at BP+2? 

How does one differentiate a DLL module from another source code module? 
Define the difference between IMPORTS and EXPORTS as appearing in the module 
definition file. 

What key API services are required for run-time DLL loading which are not required 
for load-time linking? Structurally, why are these API services needed? 

If you wished to achieve an understanding of the relationships between program 
components, would you choose a Structure Chart or a flowchart? Explain. 

What is the dominant characteristic of a C function? What are the implications of 
this characteristic for program structure? 

In C program code, when is it appropriate to use globally defined variables? Why 
are these variables generally considered undesirable to program understanding? 
Why is the include file “pmwin.h” not available as part of OS/2 Version 1.0? 

In defining the three-dimensional surface, the grid of points is defined in the x-y 
plane and facets established by connecting cyclically the projected points defined by 


the surface itself. In plotting the resulting surface, the points are collapsed along the 
x-axis. Why is this necessary? 
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5.12 Why are all lines appearing in Figures 5.19 through 5.23 not removed using the cri- 
teria that a negative direction to the facet normal constitutes a hidden line? 


5.13 Show that the limit of Equation (5.13) is A? when (x, y) = (0, 0). 
5.14 In the surface plotting program appearing in Figure 5.14, the disk read function, 
xarray_diskrd(), is called prior to setting the CGA screen mode. Why? 


5.15 In Figure 5.17 ,how would the function threeD_facets() change (aside from removal 
of the define and include statement associated with OS/2) if this routine were to exe- 
cute in a normal Real Mode program? 


Appendices 


A IBM Macro 
Assembler/2 


In this appendix we present the IBM Macro Assembler/2, which can be used to 
program the assembler under both DOS and OS/2 [1, 2]. In the early chapters all 
programming was accomplished in assembly language. A major consideration, 
however, is how desirable is this choice of language for the IBM microcomputer en- 
vironment? The answer lies in how the programmer intends to use the assembly lan- 
guage. Basically, assembler is very programming intensive and serves best when 
access of the system hardware is important. For the OS/2 Kernel service functions 
this is particularly important when acquiring or writing to the display, the video 
services (Vio), or the DOS functions (Dos) within the API. In addition to access of 
the system hardware, another associated requirement should be mentioned: rapid 
access of the hardware. The assembler is ideally suited for this requirement but has 
the added stipulation that the programmer must be prepared to devote considerable 
effort to writing very low-level code. 

In this book an alternative language, the C programming language, is consid- 
ered. C is more ideally suited for programming applications that require higher-level 
functions to accomplish tasks. Typical examples of these functions are sine and 
cosine, other hyperbolic and trigonometric functions, and a multitude of mathemati- 
cal and statistical special-purpose functions. These can all be built up from assem- 
bly language programs by the user, but it is usually more desirable to access these 
functions through a high-level language, using the assembler-constructed libraries 
within the language. The general experience is, however, that the API calls are 
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easier to implement in assembler since the API in OS/2 is presented as a generic as- 
sembler interface. C provides such an interface but is sophisticated and relies on the 
use of special macro libraries (see Appendix C) to set up the API function calls. 
With these thoughts in mind, let us briefly summarize the IBM Macro Assem- 
bler/2. We will not attempt to illustrate examples of the language; the early chapters 
accomplish that. In this appendix we merely present the assembler constructs in 
tabular form based on reference 3. Table A.1 presents the addressing modes for the 
language. There are seven forms of addressing within the Macro Assembler. Table 
A.2 contains brief descriptions for the basic instruction set common to the Intel 8086 


TABLE A.1 MACRO ASSEMBLER ADDDRESING MODES 


Mode Comment 
Immediate A byte or word constant in the source operand is loaded into a 
register operand. Example: mov ax, 18. 
Register Register destination operands are loaded from register source ope- 
rands. Example: mov ds,ax. 
Direct A register destination operand is loaded with the value of a location 


specified by its offset added to DS. Example: mov ax,dddw, where 
dddw is a variable in the data segment (addressed by DS). 


Register indirect The effective address (segment offset) is contained in BX, BP, SI, 
or DI, and this is used to load a register. Example: 


mov bx» OFFSET dddw 
mov ax+[Lbx] 


Here the brackets indicate bx contains an address. 


Base relative The effective address for the source is obtained by adding a displace- 
ment to BX or BP, which are assumed to contain an offset, Example: 


mov be +OFFSET dddw 
mov ax »CLbp+d4] 


Direct indexed Here the effective source address is the sum of an index register 
(SI or DI) and an offset. Example: 


mov 5194 
mov ax»dddw[siJ 


This loads ax with the same value as loaded in the base relative 


example. 

Base indexed Typically, the effective source address is the sum of a base register 
(BX or BP), an index register (SI or DI), and a displacement. 
Example: 


mov bx »sOFFSET dddw 
mov 61+4 
mov ax»sCbxJ][sit+2] 
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TABLE A.2 MACRO ASSEMBLER INSTRUCTIONS (8086 CONVENTION) 


Instruction 


Arithmetic 
ADC dest,src 


ADD dest,src 
DIV src 


IDIV src 


IMUL src 


MUL src 
SBB dest,src 


SUB dest,src 


Logical 
AND dest,src 


NEG dest 
NOT dest 

OR dest,src 
TEST dest,src 
XOR dest,src 


Move 
MOV dest,src 


MOVS dest-str, 


src-str 


Load 
LODS src-str 


Purpose 


Add with carry 


Addition 
Unsigned divide 


Signed integer 
division 

Signed integer 
multiply 

Unsigned multiply 


Subtract with bor- 
TOW 


Subtract 


Logical AND 


Two’s complement 
Logical NOT 
Logical inclusive 


OR 


Logical compare 


Exclusive OR 


Move 


Move byte or word 
string 


Load byte or word 
string 


Comments 


Performs an addition of the two ope- 
rands and adds one if CF is set. 


Adds the two operands. 


Divides the numerand (AL and AH for 
byte division and AX and DX for 
word division) by src. The result 
is returned in AL (byte) or AX 
(word). 

Signed division using the registers of 
DIV. 


Multiplies AL or AX times src. 


Same as IMUL. 


Subtracts the two operands and sub- 
tracts one if CF is set. 


Subtracts the two operands. 


Performs the bit conjunction of the two 
operands: the result is zero except 
when both bits are set. 


Forms the two’s complement of dest. 
Inverts dest bit by bit. 


Performs the bit logical inclusive dis- 
junction of the two operands: returns 
a one except when both bits are zero. 


Performs the bit conjunction of the two 
operands with only the flags affected. 


Performs the bit logical exclusive dis- 
junction of the two operands: returns 
a one when one operand is zero. 


Moves: 
. To memory from AX (AL) 
. To AX (AL) from memory 
. To seg-reg from memory/reg 
. To reg from seg-reg 
. To reg from reg 
To reg from memory 
To memory from reg 
6. To reg from immediate 
7. To memory from immediate 
Transfers a byte or word string from 
src, addressed by SI, to dest, ad- 
dressed by DI. 


MnP WN 


Transfers a byte (word) from src, ad- 
dressed by SI, to AL (AX) and ad- 
justs SI. 
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Instruction 


LAHF 
LDS dest,src 


LEA dest,src 
LES dest,src 


Loop 
LOOP short-label 


LOOPE short-label 


LOOPNE short- 
label 


Stack 
POP dest 


POPF 
PUSH src 
PUSHF 


Count 
DEC dest 
INC dest. 
Flags 
CLG 
CLD 
CLI 
CMC 


STC 
STD 
oa 
Shift 
SAL dest,cnt 


SHL dest,cnt 
SAR dest,cnt 


SHR dest,cnt 


Rotate 
RCL dest,cnt 


IBM Macro Assembler/2 


Purpose 


Load AH from flags 


Load data segment 
register 

Load effective ad- 
dress 


Load extra segment 
register 


Loop until count 
complete 


Loop if equal 


Loop if not equal 


Pop word off the 
stack 


Pop flags off the 
stack 


Push word onto the 
stack 


Push flags onto the 
stack 


Decrement 
Increment 


Clear carry flag 

Clear direction flag 

Clear interrupt flag 

Complement carry 
flag 

Set carry flag 

Set direction flag 

Sets interrupt flag 


Shift arithmetic left 


Shift logical left 

Shift arithmetic 
right 

Shift logical right 


Rotate left through 
carry 
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Comments 


Transfers the flags to AH. 


Loads a 32-bit address into DS and 
dest (offset). 


Transfers the offset of src to dest. 


Loads a 32-bit address into ES and 
dest (offset). 


Control is transferred to short-label if 
CX # O and CX is decremented. 


Same as LOOP but control transfers 
if ZF = 1, as an additional require- 
ment. 


Same as LOOPE except ZF must equal 
0. 


Transfers a word from the stack 
(pointed to by SP) to dest. 


Transfers the word from the stack top 
to the flags register. 


src is placed on the stack top. 


The flags register is loaded onto the 
top of the stack. 


Subtract one from dest. 
Add one to dest. 


Sets Cf = 0. 
Sets DF = 0. 
Sets IF = 0. 


Changes setting of CF. 


Sets CF = 1. 
Sets DF = 1. 
Sets IF = 1. 


Shifts dest cnt bits left. CL contains 
cnt. 

Same as SAL. 

Same as SAL except shift if to the 
right. 

Same as SAR. 


Rotates dest left in wrap-around fash- 
ion cnt bits where cnt is in CL. 
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Instruction 
RCR dest,cnt 
ROL dest,cnt 
ROR dest,cnt 


Store 
STOS dest-str 


SAHF 
String 

REP 

REPNE 

SCAS dest-str 
Convert 

CWD 

CBW 


Control 
CALL target 
RET 


ESC ext-opcode, 
STC 
LOCK 


NOP 
WAIT 


ASCII 
AAA 


AAD 
AAH 
AAS 


Decimal 
DAA 


Purpose 


Rotate right through 
carry 
Rotate left 


Rotate right 


Store byte or word 
string 
Store AH in flags 


Repeat string opera- 
tion 


Repeat string opera- 
tion 

Scan byte or word 
string 


Convert word to 
doubleword 


Convert byte to 
word 


Calls a procedure 


Return from a pro- 
cedure 


Escape 


Lock bus 
No operation 
Wait 


ASCII adjust for ad- 
dition 

ASCII adjust for di- 
vision 

ASCII adjust for 
multiply 

ASCII adjust for 
subtraction 


Decimal add adjust 
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Comments 


Rotates dest right in wrap-around fash- 
ion cnt bits where cnt is in CL. 


Same as RCL except the high-order 
bit rotates into CF as well as the 
low-order bit. 


Same as ROL except to the right. 


Transfers a byte (word) from AL (AX) 
to the location pointed to by DI. 


Transfers the value in AH to the flags 
register. 


Causes the string operation that 
follows to repeat until CX = 0, 
ZF = |. 

Same as REP except ZF = 0. 


Subtracts the dest-str from AL (AX) 
one byte at a time and affects the 
flags. 


Sign extends AX into DX. 


Sign extends AL into AX. 


Calls a procedure (target). 
Returns control to the calling routine. 


Initiates the ext-opcode with operand 
src. 


Closes the bus to access. 
A do-nothing operation. 


A bus cycle state used for synchroniza- 
tion. 


Adjusts the sum for an ASCII numeri- 
cal value following addition. 

Adjusts the quotient for ASCII numeri- 
cal value following division. 

Adjusts the product for ASCII numeri- 
cal value following multiplication. 

Adjusts the difference for an ASCII 
numerical value following subtrac- 
tion. 


Adjust for decimal addition. 
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Instruction 


DAS 


I/O 
IN acc, port 


OUT port, acc 


Miscellaneous 
XCHG dest,src 
XLAT src-table 


IBM Macro Assembler/2 


Purpose 


Decimal subtract 
adjust 


Input byte/word 


Output byte/word 


Exchange 
Translate 


275 


Comments 


Adjust for decimal subtraction. 


The byte/word contents of port are 
loaded into AL/AX. 

The contents of the accumulator are 
sent to port output. 


Exchanges the source (src) with dest. 


BX is loaded with a table address. AL 
contains a location number (byte) in 
the table and this byte is replaced 
in AL. 


family of microprocessors. These instructions are grouped by category: 


. Arithmetic 
. Logical 
Move 
Load 
Loop 
Stack 
Count 
Flags 
Shift 
Rotate 
. Store 

. String 

. Convert 
. Control 
» ASCII 
» Decimal 
I/O 


OPN AN ERWN 
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. Miscellaneous 
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Table A.3 presents the jump instruction group. These instructions are used to 
achieve execution control within the langauge. They accomplish this by providing 
the capability to change the instruction execution sequence based on the outcome of 
various tests. These tests can be performed by various instructions that change the 
state of flags in the flags’ register. Table A.4 illustrates the compare instructions, 
which serve as a basis for accomplishing such testing. These instructions change the 
flags without changing the source or destination. 


TABLE A.3) JUMP INSTRUCTION GROUP 


Instruction 


JA short-label 
(JNBE) 


JAE short-label 
(JNB) 


JB short-label 
(JNAE) 
(JC) 


JBE short-label 
(JNA) 


JCXZ short-label 


Purpose 


Jump if above/ 
if not below or 
equal 


Jump if above or 
equal/if not be- 
low 


Jump if below/if 
not above or 
equal/if carry 


Jump if below or 
equal/if not 
above 


Jump if CX is zero 


Comments 


This jump is used in conjunction with the 
carry and zero flags. If either or both 
are set, no jump occurs. Suppose two 
operands are compared; then if the desti- 
nation is greater than the source (above) 
CF = ZF = 0 and the jump occurs. 
The jump is within —128 to +127 bytes 
(short-label) and unsigned operands are 
used. 


This jump is similar to JA except only the 
carry flag is examined. If a previous com- 
pare, for example, is performed and the 
destination is greater or equal to the 
source (above or equal), CF = 0 and 
the jump occurs. This is a short-label 
instruction with unsigned operands. 


This jump is the opposite of JAE. If the 
carry flag is set, the jump will occur. 
Suppose a previous compare is per- 
formed and the destination is less than 
the source (below); CF = 1 and the jump 
occurs. This is a short label instruction 
with unsigned operands. 


This jump is the same as JB except it also 
takes place if the zero flag is set (below 
or equal). It is short-label with unsigned 
operands. 


Suppose an instruction sequence causes the 
count register (CX) to decrement. When 
CX reaches 0, control would transfer to 
the short-label after execution of JCXZ. 
This is a short-label jump. 
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TABLE A.3 (Concluded) 


Instruction 


JE short-label 
(JZ) 


JG short-label 
(JNLE) 


JGE short-label 
(JNL) 


JL short-label 
(JNGE) 


JLE short-label 
(JNG) 


JMP target 
JNC short-label 


JNE short-label 
(JNZ) 
JNO short-label 


JNB short-label 
(JPO) 
JNS short-label 


JO short-label 


JP short-label 
(JPE) 
JS short-label 


Purpose 


Jump if equal/ 
if zero 


Jump if greater/if 
not less or equal 


Jump if greater or 
equal/if not less 


Jump if less/if not 
greater or equal 


Jump if less or 
equal/if not 
greater 


Jump 
Jump if no carry 


Jump if not equal/ 
if not zero 


Jump if no over- 
flow 

Jump if no parity/ 
if parity odd 

Jump if no sign/if 
positive 

Jump on overflow 

Jump on parity/ 
if parity even 

Jump on sign 
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Comments 


If the last operation to change ZF set this 
flag (gave a result of 0), JE will cause 
a jump to occur. This is a short-label 
jump. 

If ZF = O and SF = OF, the JG instruction 
will cause a jump to short-label. This 
instruction is used with signed operands. 


This instruction is the same as JG except 
ZF is not considered. If SF = OF, the 
jump occurs. This is a short-label instruc- 
tion with signed operands. 


If SF * OF, the JL instruction will result 
in a jump. This instruction is short-label 
with signed operands. 


If ZF = 1 or SF ¥ OF, the JLE instruction 
yields a short-label jump. The instruction 
is used with signed operands. 


This is a direct and unconditional jump. 
If CF = 0, this instruction yields a short- 


label jump. 
If ZF = 0, this short-label jump will occur. 
If OF = 0, this short-label jump will occur. 
If PF = 0, this short-label jump will occur. 


If SF = 0, this short-label jump will occur. 


If OF = 1, this short-label jump will occur. 
If PF = 1, this short-label jump will occur. 


If SF = 1, this short-label jump will occur. 


278 App. A IBM Macro Assembler/2 


TABLE A.4 THE COMPARE INSTRUCTION GROUP 


Instruction Purpose Comments 
CMP destination, source Compare two This instruction causes the source to 
operands be subtracted from the destination; 


however, only the flags are af- 
fected. The destination remains un- 


changed. 

CMPS destination-str Compare byte or The source string (with DI as an index 
source-str word string for the extra segment) is subtracted 
(CMPSB) from the destination string (which 
(CMPSW) uses SI as index). Only the flags 


are affected and both DI and SI 
are incremented. A typical se- 
quence of instructions could be 


MOV SI» OFFSET AAA 
MOV DI» OFFSET BBB 
CMPS AAA» BBB 


Table A.5 contains additional instructions specific to the 80286 microproces- 
sor. Table A.6 contains similar instructions for the 80386 microprocessor. Both of 
these microprocessors are designed to operate in Protected Mode. The computer used 
in writing this book was a PC AT with a 6-MHz throughput rate, as opposed to the 
4-MHz clocks associated with the IBM PC. Expansion to the PS/2 systems should 
yield even faster performance than the 80286-based system used here. Table A.7 
presents the system-oriented instructions available for the 80286 and 80386. These 
instructions are not normally accessible by the applications programmer. 

Table A.8 contains the Macro Assembler operators available to the program- 
mer, Table A.9 contains the pseudo-operations available to the Macro Assembler 
programmer, and Table A.10 contains a set of operators to be used with the macro 
pseudo-op. 

Table A.11 illustrates the coprocessor instruction set. These instructions begin 
with the letter “F” and most rely on the use of the coprocessor stack registers, ST(O) 
through ST(7), for implementation. These stack registers serve as the general-purpose 
registers for the coprocessor. Usually, ST(0) serves as the source register and ST(1) 
as the destination, particularly in implicit instructions such as FADD when used 
without operands. 


App. A 


IBM Macro Assembler/2 


279 


TABLE A.5 ADDITIONAL 80286 APPLICATION INSTRUCTIONS 


Instruction 


BOUND dest. +source 


ENTER immediate-word+s 


immediate-byte 


IMUL dest. +immediate 


INS/INSB/INSW 
dest.e-string+Port 


LEAVE 


OUTS/OUTSB/OUTSW 
Port+source-string 


POPA 


PUSH immediate 


RCL dest. »CL 


RCR dest. »CL 


ROL dest. »CL 


ROR dest. +CL 


SAL/SHL dest. »CL 


SAR dest. +CL 


SHR dest. +CL 


Purpose 


Check array index 
against bounds 


Make stack frame for 
procedure parame- 
ters 


Integer immediate 
multiply 

Input from port to 
string 


High-level procedure 
exit 
Output string to port 


Pop all general regis- 
ters 


Push immediate onto 
stack 


Rotate left through 
carry 

Rotate right through 
Calry 

Rotate left 


Rotate right 

Shift arithmetic left/ 
shift logical left 

Shift arithmetic right 


Shift logical right 


Comments 


This instruction ensures that an index (des- 
tination) is above or equal to the first 
word in the memory location defined 
by source. Similarly, it must be below 
or equal to ‘‘source + 2.’’ 


‘‘Immediate-word”’ specifies how many 
bytes of storage to be allocated on the 
stack for the routine being entered. ‘‘Im- 
mediate-byte’’ specifies the nesting 
level of the routine within the high-level 
source code being entered. 


Does a signed multiplication of destination 
by an immediate value. 

Transfers a byte or word string from the 
port numbered by DX to ES: DI. The 
operand dest.-string determines the type 
of move: byte or word. 

Executes a procedure return for a high- 
level language. 

Transfers a byte or word string from mem- 
ory at DS:DI to the port numbered by 
DX. 

Restores the eight general-purpose regis- 
ters saved on the stack by PUSHA. 
This instruction pushes the immediate data 

onto the stack. 

Same as RCL for 8088 except count can 
be 31. 

Same as RCR for 8088 except count can 
be 31. 

Same as ROL for 8088 except count can 
be 31. 

Same as ROR for 8088 except count can 
be S31: 

Same as 8088 instructions except count 
can be 31. 

Same as 8088 instruction except count can 
be 31. 


Same as 8088 instruction except count can 
be 31. 
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TABLE A.6 ADDITIONAL 80386 APPLICATION INSTRUCTIONS 


Instruction 


BSF dest.» source 


BSR dest.+ source 


BT base, offset 


BTC bases offset 


BTR base» offset 


BTS bases offset 


CWDE +» CWD 


CMPSD 


CDQ 


INSD 


LODSD 
MOVSD 


MOVSX 


MOVZX 


OUTSD 
POPAD 


POPFD 


PUSHAD 


PUSHFD 


SCASD 


SETcc dest. 


SHLD dest.» Count 


SHRD dest.» Count 


STOSD 


Purpose 


Bit scan forward 


Bit scan reverse 
Bit test 


Bit test and comple- 
ment 


Bit test and reset 


Bit test and set 


Convert word to dou- 
bleword 


Compare double- 
words 


Convert doubleword 
to quadword 


Input 

Load string operand 

Move data from 
string to string 

Move with sign- 
extend 


Move with zero- 
extend 
Output 


Pop all general regis- 
ters 


Pop stack into 
EFLAGS 


Push all general reg- 
isters 


Push EFLAGS onto 
stack 


Compare string data 


Byte set on condition 


Double-precision- 
shift left 


Double-precision 
shift night 


Store string data 


Comments 


The source word (doubleword) is scanned for a 
set bit and the index value of this bit loaded 
in destination. Scanning is from right to left. 


Scans as in BSF but reverse order. 


This instruction loads the bit value from base 
at offset in the base, into the CF register. 


This instruction loads the bit value from base 
at offset in the base, into the CF register, and 
complements the bit in base. 


This instruction loads the bit value from base 
at offset in the base, into the CF register, and 
resets the bit to 0. 


This instruction is identical to BTR, but the re- 
sulting bit is set to 1. 


This instruction converts the signed word in AX 
to a doubleword in EAX. 


This instruction compares ES: [EDI] with 
DS:[ESI]. 

Converts the signed doubleword in EAX to a 
signed 64-bit integer in the register pair 
EDX:EAX by extending the sign into EDX. 

Input from port DX to ES:[EDI] (doubleword). 

Load doubleword DS:[ESI] into EAX. 

Move doubleword DS:[ESI] to ES:[EDI]. 


Move byte to word, byte to dword, and word 
to dword with sign extend. 


Move byte to word, byte to dword, and word 
to dword with O extend. 
Output dword DS:[ESI] to port in DX. 


Pops the eight 32-bit general registers. 
Pops the 32-bit stack top into EFLAGS. 


Pushes the eight 32-bit general registers onto 
the stack. 


Pushes the EFLAGS register onto the stack. 


Compares dwords EAX and ES:({EDI] and up- 
dates. EDI. 


Stores a byte (equal to 1), if cc, the condition, 
is met (following a compare, for example). 
Otherwise, a value of 0 is stored at the destina- 
tion. 


The destination is shifted left by count. 
Same as SHLD but shift is to the right. 


Store EAX in dword ES: [EDI] and update EDI. 
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TABLE A.7 SYSTEMS-ORIENTED 80286 AND 80386 INSTRUCTIONS 


Instruction 


ARPL dest.» source 


CLTS 


LAR deste» source 


LGDT/LIDT m 


LLDT source 


LMSW source 


LSL dest.» source 


LTR source 
SGDT/SIDT m 


SLDT dest. 


SMSW dest. 


VERR/VERW source 


STR dest. 


Purpose 


Adjust RPL field of 
selector 


Clear Task Switched 
Flag 


Load access rights byte 


Load Global/Interrupt 
Descriptor Table 
register 


Load Local Descriptor 
Table register 


Load Machine Status 
Word 


Load segment limit 


Load Task Register 


Store Global/Interrupt 
Descriptor Table 
register 

Store Local Descriptor 
Table register 


Store Machine Status 
Word 


Verify a segment for 
reading or writing 


Store Task Register 


Comments 


If the RPL field of the selector (protection 
bits) in dest. is less than the RPL field 
of source, ZF = | and the RDL field of 
dest. is set to match source. 


The Task Switch Flag is in the Machine 
Status Word and is set each time a task 
change occurs. This instruction clears that 
flag. 

Destination contains a selector. If the associ- 
ated descriptor is visible at the called pro- 
tection level, the access rights byte of 
the descriptor is loaded into the high byte 
of source (low byte = 0). 


m points to 6 bytes of memory used to pro- 
vide Descriptor Table values (Global and 
Interrupt). This instruction loads these ta- 
bles into the appropriate 80286 registers. 


Source is a selector pointing to the Global 
Descriptor Table. The GDT should, in 
turn, be a Local Descriptor Table. The 
LDT register is then loaded with source. 


The Machine Status Word is loaded from 
source. 


If the Descriptor Table value pointed to by 
the selector in destination is visible at 
the current protection level, a limit value 
specified by source is loaded into this 
descriptor. 


The Task Register is loaded from source. 


The contents of the specified Descriptor Ta- 
ble register are copied to 6 bytes of mem- 
ory pointed to by m. 

The Local Descriptor Table register is stored 
in the word register or memory location 
specified by destination. 


The Machine Status Word 1s stored in the 
word register or memory location speci- 
fied by destination. 

Source is a Selector. These instructions de- 
termine whether the segment correspond- 
ing to this selector is reachable under the 
current protection level. 


The contents of the Task Register are stored 
in destination. 
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TABLE A.8 
Operator 


PTR 


Seg-reg» 
Seg-name 


Group-name 


SHORT 


THIS 


HIGH 
LOW 
SEG 
OFFSET 


TYPE 


SIZE 


LENGTH 


SHIFT 
COUNT 
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Type 


Attribute 


Attribute 


Attribute 


Attribute 


Attribute 
Attribute 
Value returning 
Value returning 


Value returning 


Value returning 
Value returning 


Record specific 


Description 


This operator has the form type PTR expression. 
It is used to override the type attribute (BYTE, 
WORD, DWORD, QWORD, or TBYTE) of a 
variable or the attribute of a label (NEAR or 
FAR). The expression field is the variable or 
label that is to be overridden. 


The segment override operator changes the segment 
attribute of a label, variable, or address expres- 
sion. It has three forms: 


seg-regz:addr-expression 
seg-name:addr-expression 
grouPp-name:addr-expression 


This operator is used when a label follows a JMP 
instruction and is within 127 bytes of the JMP. 
It has the form JMP SHORT label and changes 
the NEAR attribute. A pass 2 NOP instruction 
is avoided. 


The form of this operator is THIS type. The operator 
produces an operand whose segment attribute is 
equal to the defining segment, whose offset equals 
IP, and a type attribute defined by ‘‘type.’’ For 
example, ‘‘AAA EQU THIS WORD”’ yields an 
AAA with attribute WORD instead of NEAR 
(if used in the same code segment). 


This operator accepts a number/address argument 
and returns the high-order byte. 


This operator accepts a number/address argument 
and returns the low-order byte. 


This operator returns the segment value of the vari- 
able or label. 

This operator returns the offset value of the variable 
or label. 


For operand arguments, this operator returns a value 
equal to the number of bytes of the operand. If 
a structure name, it returns the number of bytes 
declared by STRUC. If the operand is a label, 
it returns 65534 (FAR) and 65535 (NEAR). 

This operator returns the value LENGTH xX TYPE. 

For a DUP entry, LENGTH returns the number 
of units allocated for the variable. For all others 
it returns a 1. 

This operator is used with the RECORD pseudo- 
op and is the name of the record field. The format 
of RECORD is: recordname RECORD field- 
name: width. The value of fieldname, when used 
in an expression, is the shift count to move the 
field to the far right within the byte or word. 
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Operator 


MASK 


WIDTH 


NE 


LT 


LE 


GT 


GE 


AND + 
OR» and 
KOR 


(Concluded) 


Type 


Record specific 


Record specific 


Arithmetic 
Arithmetic 
Arithmetic 
Arithmetic 


Arithmetic 


Arithmetic 
Relational 


Relational 


Relational 


Relational 


Relational 


Relational 


Logical 


Logical 
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Description 


The format of this operator is MASK recfield. It 
returns a bit mask for the field. The mask has 
bits set for positions included in the field and 0 
for bits not included in the field. 

The format of this operator is WIDTH recfield. It 
evaluates to a constant in the range 1 to 16 and 
returns the width of a record or record field. 

Returns the sum of two terms. Form: terml + 
term2. 

Returns the difference of two terms. Form: 
terml — term2. 

Returns the product of two terms. Form: term! * 
term2. 

Form: term1 MOD term2. It returns the remainder 
obtained by dividing term1 by term2. 

Form: terml SHL term2. It shifts the bits of term1 
left by the amount contained in term2. Zeros 
are filled in the new bits. 

Same as SHL except the shift is to the right. 

Form: term] EQ term2. Returns a value — 1 (TRUE) 
if term1 equals term2, or 0 (FALSE) otherwise. 

Form: term] NE term2. Returns a value — 1 (TRUE) 
if term1 does not equal term2, or 0 (FALSE) 
otherwise. 

Form: term] LT term2. Returns a value — 1 (TRUE) 
if term] is less than term2, or 0 (FALSE) other- 
wise. 

Form: term] LE term2. Returns a value — 1 (TRUE) 
if term1 is less than or equal to term2, or 0 
(FALSE) otherwise. 

Form: term1 GT term2. Returns a value — 1 (TRUE) 
if term1 is greater than term2, or 0 (FALSE) 
otherwise. 

Form: term1 GE term2. Returns a value — 1 (TRUE) 
if term1 is greater than or equal to term?2, or 0 
(FALSE) otherwise. 

These operators have the form term1 (operator) 
term2 and return each bit position as follows: 


term! bit 


term? bit AND OR XOR 


Form: NOT term. This operator complements each 
bit of term. 
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TABLE A.9 APPLICATION-ORIENTED PSEUDO-OPS 


Pseudo-op Description 


ELSE This pseudo-op must be used in conjunction with a conditional pseudo- 
op and serves to provide an alternate path. 

ENDIF This pseudo-op ends the corresponding IFxxx conditional. 

IF Form: IF expression. When the expression is true, the code following 


this pseudo-op is executed; otherwise it branches to an ELSE entry 
point or an ENDIF. IF pseudo-ops can be nested. 

IFB Form: IFB <operand>. This is the “‘if blank’’ pseudo-op and it is 
true if the operand has not been specified as in a MACRO call, 
for example. The code following the IFB is executed when operand 
is blank. Otherwise, the IP jumps to ENDIF. 


IFDEF Form: IFDEF symbol. If symbol has been defined via the EXTRN 
pseudo-op, this is true and the code following the pseudo-op is 
executed. 

IFDIF Form: IFDIF <operandl>, <operand2>. The code following this 


pseudo-op is executed if the string operand] is different from the 
string operand2. 


IFE Form: IFE expression. The code following this pseudo-op is executed 
if expression = 0. 
IFIDN Form: IFIDN <operand1>, <operand2>. The code following this 


pseudo-op is executed if the string operand! is identical to the 
string operand2. 


IFNB Form: IFNB <operand>. The code following this pseudo-op is exe- 
cuted if the operand is not blank. 

IFNDEF Form: IFNDEF symbol. The code following this pseudo-op is executed 
if the symbol has not been defined via the EXTRN pseudo-op. 

[Fi This pseudo-op is true if the assembler is in pass 1, and it is used 
to load macros from a macro library (as an example). 

IF2 This pseudo-op is true if the assembler is in pass 2, and it can be 


used to inform the programmer what version of the program is 
being used (when coupled with appropriate logic and a % OUT). 


»286C This pseudo-op tells the assembler to recognize and assemble 80286 
instructions used by the IBM AT. 

» 8086 This pseudo-op tells the assembler not to recognize and assemble 
80286 instructions. 

»8087 This pseudo-op tells the assembler to recognize and assemble 8087 
coprocessor instructions and data formats. 

ASSUME Form: ASSUME seg-reg:seg-name, . . . . This pseudo-op tells the 
assembler which segment register segments belong to. 

COMMENT Form: COMMENT delimiter text delimiter. COMMENT allows the 


programmer to enter comments without semicolons. It is not recog- 
nized by the SALUT program. 


DB Form: [variable] DB [expression]. It is used to initialize byte storage. 

DD DD has the same form as DB except it applies to doubleword quantities. 

DQ DQ has the same form as DB except it applies to four-word quantities. 

DT DT has the same form as DB except it applies to 10-byte packed 
decimal. 


DW DW has the same form as DB except it applies to word quantities. 
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Pseudo-op 


GROUP 


INCLUDE 


LABEL 


NAME 


ORG 


PROC 


PUBLIC 


+RADIX 


RECORD 


SEGMENT 


STRUC 
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Description 


Form: END [expression]. END identifies the end of the source pro- 
gram, and the optional expression identifies the name of the entry 
point. 

Form: procedure-name ENDP. Designates the end of a procedure. 

Form: structure-name ENDS or seg-name ENDS. Designates the end 
of a structure or segment. 

Form: name EQU expression. Assigns the value of expression to 
name. This value may not be reassigned. 

Form: label = expression. Assigns the value of expression to label. 
May be reassigned. 

EVEN ensures that the code following starts on an even boundary. 

Form: EXTRN name:type, . . . . EXTRN is used to indicate that 
symbols used in this assembly module are defined in another 
module. 

Form: name GROUP seg-name,. . . . GROUP collects all segments 
named and places them within a 64K physical segment. 

Form: INCLUDE [drive] [path] filename.ext. INCLUDE assembles 
source statements from an alternate source file into the current 
source file. 

Form: name LABEL type. LABEL defines the attributes of name 
to be type. 

Form: NAME module-name. NAME gives a module a name. It may 
be used only once per assembly. 

Form: ORG expression. The location counter is set to the value of 
expression. 

Form: procedure-name PROC [attribute]. PROC identifies a block 
of code as a procedure and must end with RET/ENDP. The attribute 
is NEAR or FAR. 

Form: PUBLIC symbol, . . . . PUBLIC makes symbols externally 
available to other linked modules. 

Form: .RADIX expression. .RADIX allows the default base (decimal) 
to be changed to a value between 2 and 16. 

Form: recordname RECORD fieldname: width [=exp],.. . . 
RECORD defines a bit pattern to format bytes and words for bit 
packing (see text). 

Form: segname SEGMENT [align-type] [combine-type] [‘class’] (see 
Chapter 3 for a discussion of this pseudo-op). 

Form: structure-name STRUC. STRUC is used to allocate and initial- 
ize multibyte variables using DB, DD, DQ, DT, and DW. It must 
end with ENDS. 


»CREF and This listing pseudo-op provides cross-reference information when a 
»XCREF filespec is indicated in response to the assembler prompt (CREF). 
It is the normal default condition. .XCREF results in no output 

for cross reference when in force. 
*LALL+.SALL + -LALL lists the complete macro text for all expansions. .SALL sup- 
and »XALL presses listing of all text and object code produced by macros. 
.XALL produces a source line listing only if object code results. 
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TABLE A.9 
Pseudo-op 


»«LFCOND 


»LIST and 


eALIST 


4Z0UT 


PAGE 


»SFCOND 
SUBTTL 
» TFCOND 
TITLE 


ENDM 
EXITM 


IRP 


IRPC 


LOCAL 


MACRO 


PURGE 


App. A IBM Macro Assembler/2 


(Concluded) 


Description 


This pseudo-op causes the listing of conditional blocks that evaluate 
as false. 


.LIST causes a listing of source and object code in the output assembler 
list file. .XLIST turns this listing off. These pseudo-ops can be 
used to selectively list code during the assembly of programs, 
especially long sequences of instructions. 


Form: %OUT text. This pseudo-op is used to monitor progress through 
a long assembly. The argument “‘text’’ 1s displayed, when encoun- 
tered, during the assembly process. 


Form: PAGE operand1, operand2. Controls the length (operand1) 
in lines and the width (operand2) in characters of the assembler 
list file. 


This pseudo-op suppresses the listing of conditional blocks that evalu- 
ate as false. 


Form: SUBTTL text. Generates a subtitle to be listed after each 
listing of title. 


This pseudo-op changes the listing setting (and default) for false 
conditionals to the opposite state. 


Form: TITLE text. This pseudo-op specifies a title to be listed on 
each page of the assembler listing. It may be used only once. 


ENDM is the terminator for MACRO, REPT, IRP, and IRPC. 


EXITM provides an exit to an expansion (REPT, IRP, IRPC, or 
MACRO) when a test proves that the remaining expansion is not 
needed. 


Form: IRP dummy, <operandlist>. The number of operands (sepa- 
rated by commas) in operandlist determines the number of times 
the following code (terminated by ENDM) is repeated. At each 
repetition, the next item in operandlist is substituted for all occur- 
rences of dummy. 


Form: IRPC dummy, string. This is the same as IRP except at each 
repetition the next character in string is substituted for all occur- 
rences of dummy. 


Form: LOCAL dummylist. LOCAL is used inside a MACRO struc- 
ture. The assembler creates a unique symbol for each entry in 
dummylist during each expansion of the macro. This avoids the 
problem of a multiply defined label, for example, when multiple 
expansions of the same macro take place in a program. 


Form: name MACRO dummylist. The statements following the 
MACRO definition, before ENDM, are the macro. Dummylist 
contains the parameters to be replaced when calling the macro 
during assembly. The form of this call is name parmlist. Parmlist 
consists of the actual parameters (separated by commas) used in 
the expansion. 

Form: PURGE macro-name, .. . . PURGE deletes the definition 
of a specified MACRO and allows the space to be used. This is 
beneficial when including a macro library during assembly but 
desiring to remove those macros not used during the assembly. 
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TABLE A.10 SPECIAL-PURPOSE MACRO OPERATORS 
Operator Description 


& Format: text&text. This operator concatenates text or symbols. An example 
is 


TC1 MACRO K 
LEA DX + CHAR&XK 
MOY AH: 9 
INT 21H 
ENDM 


Here a call TC1 A would load DX with a character start position CHARA. 


13 Format: ;;text. A comment preceded by two semicolons is not produced 
as part of the expansion when a MACRO or REPT is defined in an 
assembly. 


Format: !character. Causes the character to be interpreted as a literal 
value, not a symbol. 


hs Format: %expression. Converts expression to anumber. During expansion, 
the number is substituted for expression. Consider 


MAC1 MACRO x 
Lt = KX * 1000 
MAC2 ALL +k 
ENDM 
4 


MAC2 MACRO YuX 


PROD&X DB ‘Production Nos &X = &Y’ 
ENDM 
This yisids ‘‘PRODS DB ‘Production No. 5 = 5000,’ ”’ 


when called with MACI1 5. 
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TABLE A.11 COPROCESSOR INSTRUCTION SET 
Instruction Purpose Comments 
Data transfer 
FLD source Load real Pushes the source data onto the top of the 
register stack, ST(Q). 
FST destination Store real This instruction copies ST(Q) into the indicated 


FSTP destination 


FXCH destination 


FILD source 


FIST destination 


FISTP destination 


FBLD source 


FBSTP destination 


Addition 
FADD 


FADDP destination» 
source 


FIADD integer- 
memory 


Subtraction 
FSUB 


FSUBP destinations 
source 


Store real/pop 


Exchange ST 
Load integer 


Store integer 


Store integer/ 
pop 


Load BCD 


Store BCD/pop 


Real addition 


Real add/pop 


Integer addition 


Real subtraction 


Real subtract/ 
pop 


destination (real), which can be a memory 
operand or register. 


This instruction copies ST(Q) into the indicated 
destination and then pops ST(Q) off the 
stack. 


This instruction exchanges ST(Q) with the in- 
dicated destination. 


This instruction pushes the source data (in- 
teger) onto the top of the stack, ST(Q). 


This instruction stores ST(Q), the stack top, 
in the indicated destination, which must be 
an integer memory operand. 


This instruction stores ST(O), the stack top, 
in the indicated destination, which must be 
an integer memory operand, and then pops 
ST(O) off the stack. 


This instruction pushes the source, which must 
be a BCD number, onto the stack at ST(0). 


This instruction stores ST(0) as a BCD number 
at the destination and pops ST(O) off the 
stack. 


This instruction can be used without operands 
[assumes ST(1) added to ST(Q) with the 
result in ST(O)], with a real-memory op- 
erand added to ST(0), or with explicit refer- 
ence to ST(0O) added to another register. 

The source is ST(O) and the destination must 
be another stack register. The result is left 
in the alternate stack register used as the 
destination. 

The destination, ST(0), is added to the source, 


integer memory, and the sum returned in 
ST(O). 


This instruction can be used without operands 
[assumes ST(1) is the destination and ST(O) 
is subtracted from it with the result in 
ST(1)], with a real-memory operand sub- 
tracted from ST(0) and the result in ST(Q), 
or with explicit reference to ST(O) and an- 
other register (the destination containing the 
result). 

The source, ST(0), is subtracted from the des- 
tination, another stack register, and the re- 
sult stored in the destination. 
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TABLE A.11 = (Continued) 


Instruction Purpose 
FISUB source Integer subtrac- 
tion 
FSUBR Real reversed 
subtract 
FSUBRP Real reversed 
subtract/pop 
FISUBR source Integer reversed 
subtract 
Multiplication 
FMUL Real multiply 
FMULP destination» Real multiply/ 
source pop 
FIMUL source Integer multiply 
Division 
FDIV Real divide 
FDIVP destinations Real divide/pop 
source 
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Comments 


The destination, ST(0), has the source op- 
erand, an integer-memory operand, sub- 
tracted from it and the result is stored in 
ST(O). 


The destination is subtracted from the source 
and the result left in the destination. The 
operand configuration is the same as for 
FSUB. 


This instruction is the same as FSUBP except 
the destination is subtracted from the 
source. ST(O) still serves as the source op- 
erand. 


This instruction is the same as FISUB except 
the destination is subtracted from the 
source. The source is still an integer-mem- 
ory operand. 


This instruction multiplies the destination op- 
erand by the source and returns the product 
in the destination. The instruction can be 
executed with no operands [ST(Q) is the 
implied source and ST(1) the destination], 
with the source specified as a real-memory 
operand and ST(0) the destination, and with 
both destination register and source register 
[one of which is ST(Q)] specified. 


This instruction uses ST(Q) as the source op- 
erand and another register as the destination. 
The product is returned in the destination 
register and the stack top popped. 


This instruction multiplies the destination by 
the source and returns the product in the 
destination. The destination is ST(O) and 
source is an integer-memory operand. 


This instruction divides the destination by the 
source and returns the quotient to the desti- 
nation. The instruction can be executed with 
no operands [ST(O) is the implied source 
and ST(1) the implied destination], with a 
source specified and ST(0) the implied desti- 
nation, and with a source [ST(0)] and desti- 
nation (another register) specified. 


This instruction divides the destination by the 
source and returns the quotient to the desti- 
nation. It then pops the top of the 8087 
stack. The source is the ST(O) register and 
the destination operand is another stack reg- 
ister. 
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TABLE A.11 (Continued) 
Instruction Purpose Comments 


FIDIV source 


FDIVR 


FDIVRP destination» 
source 


FIDIVR source 


Miscellaneous 
FSQORT 


FSCALE 


FPREM 


FRNDINT 


FXTRACT 


FABS 


FCHS 
Comparison 
FCOM 


FCOMP 


FCOMPP 


Integer divide 


Real reversed 
divide 


Real reversed 
divide/pop 


Integer divide 
reversed 


Square root 


Scale 


Partial remain- 
der 


Round to integer 


Extract expo- 
nent/sig- 
nificand 


Absolute value 


Change sign 


Real compare 


Real compare/ 
pop 


Real compare/ 
pop twice 


This instruction divides the destination by the 
source and returns the quotient to the desti- 
nation. The destination is ST(O) and the 
source is an integer-memory operand. 


This instruction is identical with FDIV except 
the source is divided by the destination. 
The quotient is still returned in the destina- 
tion. 


This instruction is identical to FDIVP except 
the source is divided by the destination. 
The quotient is still returned in the destina- 
tion. 


This instruction is identical to FIDIV except 
the source is divided by the destination. 
The quotient is still returned in the destina- 
tion. 


This instruction replaces the content of ST(0) 
with its square root. 


This instruction interprets the value of the 
number contained in ST(1) as an integer. 
This value is added to the exponent of the 
number in ST(Q), which is equivalent to 
multiplying ST(Q) by 2 raised to this integer 
power. 

This instruction takes the modulo of ST rela- 
tive to the number contained in ST(1). The 
Sign is the same as that of ST(0). 


This instruction rounds ST(Q) to an integer. 
The rules for rounding are determined by 
setting the RC field of the control word. 
RC = 00 (round to nearest integer), 01 
(round downward, 10 (round upward), and 
11 (round toward Q). 

This instruction reduces the number in ST(0) 
to a significand and an exponent for 80- 
bit arithmetic. 

This instruction yields the absolute value of 
ST(O). 

This instruction reverses the sign of ST(O). 


This instruction compares the source operand 
[which can be specified as a real-memory 
operand or implicit as ST(1)] and ST(O). 

This instruction is identical with FCOM except 
the stack top, ST(O), is popped following 
the compare. 

This instruction is identical with FCOM except 
the stack top, ST(0), and ST(1) are popped 
following the compare. 
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Instruction 


FICOM source 


FICOMP source 


FTST 


FKAM 


Transcendental 
FPTAN 


FPATAN 


F2XM1 


FYLZA 


FYLZArs 


Constant 
PLOZ 
FLD1 
riLOPi 
FLOLZT 


FLDLZE 

FLDLG2 

FLDLN2 
Control 


FINIT/FNINIT 


FDISI/FNDISI 
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Purpose 


Integer compare 


Integer compare/ 


pop 


Test 


Examine 


Partial tangent 


Partial arc tan- 
gent 


Ze 


Y * log,(X) 


Y * log, 
(oF a) 


Load zero 
Load +1.0 
Load pi 

Load log,(10) 


Load log,(e) 
Load logj(2) 
Load log,(2) 


Initialize proc- 
essor 

Disable inter- 
rupts 
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Comments 


This instruction compares ST(0) to the source 
operand, which is an integer-memory op- 
erand. 

This instruction is identical to FICOM except 
the stack top, ST(0), is popped following 
the compare. 

This instruction tests ST(Q) relative to +0.0. 
The result of the test is returned 1n the condi- 
tion code of the status word: (C3, CO) = 
(0, 0) for ST positive, (0, 1) for ST negative, 
(1, 0) for ST zero, and (1,1) if ST cannot 
be compared. 

The stack top, ST(QO), is examined and the 
result returned in the condition code field 
as specified in the Version 2.0 Macro As- 
sembler Reference manual. 


This instruction calculates Y/X = TAN(z). 
The value z is contained in ST(O) prior to 
execution. Following execution, Y is con- 
tained in ST(1) and X contained in-ST(0). 

This instruction calculates z = ARCTAN(Y/ 
X), where X is ST(O) and Y is ST(1). The 
result, z, is returned to ST(O). 

This instruction calculates 2* — 1, where x 
is taken from ST(O) and must be in the 
range (0, 0.5). The result is replaced in 
ST(0). 

This instruction calculates Y * log,(X), where 
X is ST(O) and Y is ST(1). The stack top 
is popped and the result returned to the 
new ST(O). 

This instruction is the same as FYL2X except 
1 is added_to X. X must be in the range 
(0, 1 — V'2/2). 


This instruction loads +0.0 in ST(O). 

This instruction loads +1.0 in ST(Q). 

This instruction loads pi into ST(0). 

This instruction loads log,(10) into the stack 
top, ST(Q). 

This instruction loads log,(e) into ST(0). 

This instruction loads log,9(2) into ST(O). 

This instruction loads log.(2) into ST(0). 


This instruction accomplishes a hardware reset 
of the 8087. 

This instruction prevents the 8087 from issu- 
ing an interrupt request. 
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TABLE A.11 (Concluded) 


Instruction Purpose Comments 
FENI/FNENI Enable inter- This instruction is the reverse of FDISI and 
rupts clears the interrupt mask in the control 
word. 
FLDCW source Load control This instruction replaces the current control 
word word with the word defined by the source 
operand. 
FSTCW/FNSTCW Store control This instruction writes the current control 
destination word word to the memory location defined by 
destination. 
FSTSW/FNSTSW Store status This instruction writes the current status word 
destination word to the memory location defined by destina- 
tion. 
FCLEX/FNCLEX Clear excep- Clears all exception flags, the interrupt request 
tions and busy flag. 
FSTENV/FNSTENV Store environ- Writes the basic status and exception pointers 
destination ment to the memory location defined by destina- 
tion. 
FLDENY source Load environ- Reloads the 8087 environment from the mem- 
ment ory area defined by the source. 
FSAVE/FNSAVE Save state Writes the environment and register stack to 
destination the memory location specified by the desti- 
nation operand. 
FRSTOR source Restore state Reloads the 8087 from the source operand. 
FINCSTP Increment stack Adds 1 to the stack pointer. 
pointer 
FFREE destination Free register Changes the destination’s tag to empty. 
FDECSTP Decrement stack Subtracts 1 from the stack pointer. 
pointer 
FNOP No operation Causes no operation. 
FWAIT Wait instruc- Causes the 8088 to wait until the current 8087 
tion instruction is complete before the 8088 ex- 


ecutes another instruction. 
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B Microsoft C 
Compiler Version 5.1] 


In Part III of this book the OS/2 Kernel was programmed using the C language. The 
specific C implementaion used was the Version 5.1 C Optimizing Compiler devel- 
oped by the Microsoft Corporation [1-3]. This compiler was one of the first that 
was made commercially available that would execute in the Protected Mode, so that 
it could be used with OS/2. Associated with the compiler is a Toolbox that is dis- 
cussed in Appendix C. This Toolbox provides high-level C interfaces to the OS/2 
API. These interfaces are suitable for use with the Microsoft C compilers and are 
provided as a set of .h include files. 

In this appendix we briefly review some of the C language syntax used in this 
book. We assume that the reader has a familiarity with C, hence we only provide 
this appendix for reference. The following categories are mentioned: 


1. Control structures 

2. Operators 

3. Data.types and storage classes 
4. Other syntax 


The treatment of this appendix is similar to that given in Applied C: The IBM Mi- 
crocomputers [4]. 

The basic control structures fall into three categories: loops, decision structures, 
and jumps. Loops consist of the for, while, and do while syntax. The for loop struc- 
ture takes the form, for example: 
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for (k=1;k<=N;k++) 
{ 


statements 


} 
The while loop has the form 


while(expression) ) 
{ | 


statements 


} 


where expression is returned as a TRUE or FALSE value. When TRUE the state- 
ments in the brackets are executed. Otherwise, the processing passes to subsequent 
statements, outside the brackets. 

The do while loop has an inverted structure with a test at the end of the loop: 


do 
{ 


statements 


} while(expression) 


Here statements are executed the first time through the loop and each subsequent 
time that expression evaluates TRUE. 

Decision structures are represented by the if, else, case, switch, and default \ 
statements. The if structure is of the form ) 


if (expression) 


{ 


statements 


} 


where a TRUE value for expression causes the statements to be executed. The else 
statement appears as follows, and is used in conjunction with the if statement: 


if (expression) 


{ 


statements 


} 


else 


{ 


alternate statements 
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Here the alternate statements are executed when expression is FALSE. The case, 
switch, and default statements work together. Consider the following structure: 


switch (expression) 


{ 


case As: 
statement #1; 
break; 

case B:; 
statement #2; 
break; 

case Cs: 
statement #3; 
break; 


default: 
statement N; 
break; 


Here, if the value of expression takes on A, B, C, ... the corresponding case se- 
quence is executed. For all values not specified with a subsequent case statement, 
the default statement sequence is executed. 

The switch decision structure is used frequently in the Presentation Manager 
windows processing. We do not use this structure because the examples in this book 
did not involve multiple options. The break syntax was used to jump around subse- 
quent statements once the preceding statement had been executed. 

There are two statements that can be used to alter the sequence of processing. 
These are the jump statements, continue and goto. Consider the following loop: 


for(expressionl1) 


{ 


statements 


if{expression2 ) 


{ 


alternatel statements 


continue; 


} 
if (expression3) 
{ 


alternate2 statements 


296 App. B Microsoft C Compiler Version 5.1 


When expression2 is evaluated TRUE, the associated statements are executed. Once 
the continue statement is executed, the processing jumps to the end of the loop 
without entering the second if structure regardless of whether expression3 is TRUE 
or FALSE. 

Table B.1 illustrates the major operators found in the C language. Table B.2 


TABLE B.1 C OPERATORS 
Operator Discussion 


a Grouping 

{} Executes all contained syntax 

++ Increment 

- Decrement 

Multiply 

Divide 

Add 

Subtract 

Less than 

Greater than 

Less than or equal 

Greater than or equal 

AND: logical 

OR: logical 

Equal: assignment 

Adds right-hand quantity to left hand 
Subtracts right-hand quantity from left hand 
Multiplies left hand by right hand 

Divides left hand by right hand 

Equal to: relational 

Not equal to: relational 

Modulus 

Modulus after dividing left hand by night hand 
Pointer: gives the value at the pointed address 
Pointer: gives the address of the variable 


Wm Pv navy na 1 tN KI 
-- Fn ot 
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TABLE B.2. ADDITIONAL C OPERATORS 


Operator Discussion 

(type) Changes the type of a variable 

sizeof Returns the size in bytes of the variable 
-> Assigns a structure member 


‘ Assigns a structure member 
NOT: bitwise 
Takes one’s complement: bitwise 


& AND: bitwise 

7 EXCLUSIVE OR: bitwise 
OR: bitwise 

2: Conditional operator 

é< Left shift: bitwise 

» Right shift: bitwise 
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contains some additional operators of less utility. The basic C data types are as 


follows: 


int 

long 
short 
unsigned 


char 
float 
double 


integer (2 bytes); signed 
integer (4 bytes); signed 
integer (2 bytes); signed 
integer; zero or positive values 


unsigned int (2 bytes); 0 - 255 
unsigned long (4 bytes); 0 =- 65535 
unsigned short (2 bytes); 0 —- 255 


= character (1 byte) 38 38 


floating (4 bytes); -10307 - +10307 
floating (8 bytes); -10 - +10 


Within the OS/2 Kernel programming are a number of additional derived types 
used by Microsoft and IBM to expand the flexibility of OS/2. Some of these types 


are 
SEL 


PSEL 
SHANDLE 
BYTE 
PCHAR 
HFILE 
HSEM 
PUINT 
HVIO 
TLD 


segment selector 

pointer to selector 

handle 

byte (char) 

pointer to character 

handle to file 

handle to semaphore 
pointer to unsigned integer 
handle to video context 
thread ID 


The addition of the Presentation Manager files adds many more derived types to the 


OS/2 inventory. 


The basic C storage classes are auto, external, static, and register: 


auto 


external 
static 


register 


generated with temporary duration within a module as a 
local class 


generated for all time as a global 
generated for all time but local in scope 


generated with temporary duration within a module as 
local and, if possible, associated with a CPU register 


The remaining topics to be briefly examined are functions, structures, unions, 
and pointers. This, then, will complete our look at the C syntax. The examples in 
the text are intended to provide additional insight into the C language and its appli- 
cability in the OS/2 programming environment. 
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In many respects C is the language of choice for programming the API once 
the programmer obtains a familiarity with its features. Certainly, C is the choice for 
programming the Presentation Manager [5]. 

The structure for a function in C has the following form: 


function_name() 


formal parameter types 


{ 


local parameter types 
statements 


return expression; 


} 


Here the lines of code immediately following the function definition statement 
contain the typing for formal parameters. The function brackets are next, with the 
local parameter typing contained within the function brackets, together with all re- 
maining function statements. If a value such as d is to be returned, this value is as- 
signed and used as the argument of a return( ) statement. 

A structure, for example, can look as follows: 


struct tag _name 


{ 


type declarations 


} struct_name; 


This architecture allows a tag name identifier, tag name, to be used with later 
definitions to define a structure that has similar characteristics. For example, the 
structure 


struct car 


{ 


char olds, chevy, pontiac; 
char accura, honda, mazda; 
char ford, lincoln, mercury; 
} car_type, *pcar_ type; 


has as tag, car, and as structure name, car_type. The structure elements can be 
accessed using a period to offset the element from the structure name. In the struc- 
ture above the fifth element is accessed using 


car_type.-honda = ... 


App. B Microsoft C Compiler Version 5.1 299 


We can use pointers to access this structure through the same approach; for ex- 
ample, the fifth element can be accessed using 


pear _ type -> 


These two statements have identical results. 

In a structure, space is reserved for each element. In a union, space is reserved 
only for the largest element; all other elements must share this space. For example, 
in the following template: 


union 


{ 

Lnt oe 

int d; 

float g; 

double h; 

} letter, *pletter; 


the largest amount of space reserved for the union is 8 bytes with the h variable. All 
the remaining variables must share the space in storage with this variable amount. 
Since c and d each occupy 2 bytes and g occupies 4 bytes, this union can be used 
to store c, d, and g simultaneously, or, alternatively, h or other combinations less 
than or equal to 8 bytes. 

This discussion completes our brief look at C. We have attempted to touch 
only on those syntax features that are used in programming the OS/2 Kernel. 


REFERENCES 


1. Microsoft C 5.1 Optimizing Compiler: CodeView, and Utilities, Microsoft Editor, Mixed- 
Language Programming Guide, Microsoft Corporation, Redmond, WA, 1987. 

2. Microsoft C 5.1 Optimizing Compiler: Run-Time Library Reference, Microsoft Corpora- 
tion, Redmond, WA, 1987. 

3. Microsoft C 5.1 Optimizing Compiler: User’s Guide and Language Reference, Microsoft 
Corporation, Redmond, WA, 1987. 

4. Godfrey, J. T., Applied C: The IBM Microcomputers, Prentice-Hall, Inc., Englewood 
Cliffs, NJ, 1990. 


5. Petzold, C., Programming the OS/2 Presentation Manager, Microsoft Corporation, Red- 
mond, WA, 1989. 


C Function Declarations 
and Macros Used 
TO Interface The API 


The IBM Programmer’s Toolkit Versions 1.0 and 1.1 [1.2] contain a set of assem- 
bler macros and C function declarations that provide interfaces to the API services. 
In addition, Version 1.1 contains macros and C function declarations for accessing 
the Presentation Manager (PM). In this appendix we address similar interfaces for 
C and assembler and provide the relevant code for the macro calls (assembler) and 
function declarations (C) used in this book. The reader is referred to the Toolkit for 
a complete discussion of similar macros and function declarations. 


C.1 THE ASSEMBLER INTERFACE 
The primary assembler include file in Version 1.0, and available under Version 1.1, 
is 
sysmac.inc 


This, in turn, calls 


doscalls.ince 
subcalls.inc 


which loads Dos, Mou, Kbd, and Vio service macros. 
Under Version 1.1, a new set of include files is provided with variable entry 
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points determined by symbols such as INCL_BASE. Typically, these include files 


are: 


Level I (OS/2): 
Level 2 (OS/2): 


Level 3 (OS/2): 


Level 2 (PM): 


Level 3 (PM): 


os/2.inc (includes os/2.def.inc.bse.inc, and pm.inc) 
os/2def.inc (defines constants, types, error codes, and struc- 
tures) 

bse.inc (includes bsedos.inc, bsesub.inc, and bseerr.inc) 


bsedos.inc (defines constants, structures, and prototypes for 
the Dos API) 

bsesub.inc (sets up calls for Vio, Kbd, and Mou API) 
bseerr.inc. (sets up error code constants for all API calls) 
pm.ine (includes pmwin.inc, pmgpi.inc, pmdef.inc, 
pmavio.inc, pmspl.inc, pmpic.inc, pmord.inc, pmbitmap.inc, 
pmfont.inc) 

pmwin.inc (sets up windows, message manager, keyboard, 
mouse, and dialog manager API calls) 

purgpi.inc (sets up Gpi API calls) 

pmdev.inc (sets up device context API calls) 

pmavio.inc (sets up the PM Vio API calls) 

pmspl.inc [sets up the spool (Spl) API calls] 

pmpic.inc (sets up the picture API calls) 

pmord.inc (sets up the GOCA orders for the Gpi API calls) 
pmbitmap.inc (sets up the bitmap types) 

pmfont.inc (sets up the types for fonts) 


These include files contain macros for loading API service routines and push- 
ing the stack with appropriate parameter data. In this appendix it is desirable to 
present a similar set of macro-based or function calls used in the assembly language 
in this book. These macros bridge the gap between the macro calls used in the text 
and the actual assembler code required to lead a particular API service. They are 
very similar to the macros available through the Toolkit. We ignore the error-pro- 
cessing features of the Toolkit macros and leave the addition of these features to the 
reader. With these thoughts in mind, let us begin with several subordinate macro 


definitions: 


@pw 


@def 


macro m1 ;push word 

mov ax,ml 

push ax 

endm 

macro nm ;define API entry 
ifndef nm 

extrn nm:far 

endif 


endm 
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@ps macro 
MOv 
push 
MOv 
push 
endm 
@pd macro 
push 
push 
Mov 
MOv 
Mov 
push 
MOv 
push 
push 
pop 
xchg 
pop 
Mov 
pop 
pop 
push 
endm 
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ml 
ax, 
ax 
ax, 
ax 


*push address 
SEG ml 


OFFSET ml 


ml 
ds 
bx 
ax, 
ds, ax 

bx, OFFSET ml 
word ptr [bx] 
ax, [bx+2] 

bp 

sp 

bp 
[bpt+6], 
bp 
ds, 
ax 
bx 
ax 


spush doubleword 


SEG ml 


ax 


ax 


With these preliminary macros defined it is now possible to define the macro calls 


used in the book. 


macro 
@def 
@pw 
@pw 
@ps 
@pw 
@pw 
call 
endm 


@DosAllocHuge 


use: Figure 3.12 


macro 
@def 
@pw 
@ps 
@pw 
call 
endm 


@DosAllocSeg 


use: Figure 3.1, 3.8, 3.15, 3.25b 


ml, m2, m3, m4, m5 

DOSALLOCHUGE 

ml sno. segments 
m2 ;size last seg 
m3 selector 

m4 ;max seg 

m5 ;flags 

far ptr DOSALLOCHUGE 

ml, m2, m3 

DOSALLOCSEG 

m1 ;no. bytes 
m2 selector 
m3 *flags 


far ptr DOSALLOCSEG 
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@DosAllocShrSeg macro 
@def 
@pw 
@ps 
@ps 
call 
endm 


use: Figure 3.4, 3.22b 


@DosBeep macro 
@def 
@pw 
@pw 
call 
endm 
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use: Figure 3.17b, 3.18b, 3.20b, 3.21b, 3.22b, 3.23b, 3.24b, 3.25b 


@DosClose macro 
@def 
@pw 
call 
endm 


use: Figure 2.1, 2.6b, 3.3, 3.4 


@DosCloseQueue macro 
@def 
@pw 
call 


endm 
use: Figure 3.24b, 3.25b 


@DosCreateQueue macro 
@def 
@ps 
@pw 
@ps 
call 
endm 


use: Figure 3.24b 


@DosCreateSem macro 
@def 
@pw 
@ps 


@ps 


ml, m2, m3 

DOSALLOCSHRSEG 

ml ;no. bytes 
m2 *name 

m3 sselector 
far ptr DOSALLOCSHRSEG 

ml, m2 

DOSBEEP 

ml shertz 

m2 *duration 
far ptr DOSBEEP 

ml 

DOSCLOSE 

ml shandle 
far ptr DOSCLOSE 

ml 

DOSCLOSEQUEUE 

ml shandle 
far ptr DOSCLOSEQUEUE 

ml, m2, m3 

DOSCREATEQUEUE 

ml shandle 
m2 spricrity 
m3 *name 

far ptr DOSCREATEQUEUE 

ml, m2, m3 

DOSCREATESEM 

ml sno exclusive 
m2 s;handle 


m3 sname 
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call far ptr DOSCREATESEM 
endm 


use: Figure 3.20b, 3.22b 


@DosCreateThread macro ml, m2, m3 
@def DOSCREATETHREAD 


@pd m1 ;address 
@ps m2 sthread ID 
@pd m3 send stack 
call far ptr DOSCREATETHREAD 
endm 
use: Figure 3.17b, 3.18b 
@DosExecPgm Macro ml, m2, m3, m4, m5, m6, m7 

@def DOSEXECPGM 

@ps m1 sname buffer 

@pw m2 ; length 

@pw m3 *flags 

@ps m4 sargpointer 

ps m5 ;envpointer 

@ps m6 sretrun 

@ps m7 ;pgmpointer 

call far ptr DOSEXECPGM 

endm 


use: Figure 3.4, 3.20b, 3.22b, 3.24b 


@DosExit Macro ml, m2 
@def DOSEXIT 
@pw m1 ;action 
@pw m2 sresult 
call far ptr DOSEXIT 
endm 


use: all processes 


@DosFreeSeg Macro ml 
@def DOSFREESEG 
@pw ml ;selector 
call far ptr DOSFREESEG 
endm 


use: Figure 3.1, 3.4, 3.5, 3.12, 3.15, 3.24b, 3.25b 


@DosGetHugeShiftmacro ml 
@def DOSGETHUGESHIFT 
@ps m1 sshiftcount 
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use: Figure 3.12 


@DosGetShrSeg 


use: Figure 3.5, 3.23b 


@DosGiveSeg 


use: Figure 3.25b 


@DosKillProcess 


call 
endm 


macro 
@def 
@ps 
@ps 
call 
endm 


macro 
@def 
@pw 
@pw 
@ps 
cali 
endm 


macro 
@def 
pw 
@pw 
call 
endm 
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far ptr DOSGETHUGESHIFT 


ml, m2 
DOSGETSHRSEG 
ml 

m2 


far ptr DOSGETSHRSEG 


ml, m2, m3 
DOSGIVESEG 

ml 

m2 

m3 

far ptr DOSGIVESEG 


ml, m2 
DOSKILLPROCESS 
ml 

m2 


far ptr DOSKILLPROCESS 


use: Figure 3.4, 3.20b, 3.22b, 3.24b 


@DosMakePipe 


use: Figure 3.22b 


@DosOpen 


macro 
@def 
@ps 
@ps 
@pw 
call 
endm 


macro 
@def 
@ps 
@ps 
@ps 
@pd 


ml, m2, m3 
DOSMAKEPIPE 

ml 

m2 

m3 

far ptr DOSMAKEPIPE 


ml, m2, 
DOSOPEN 
ml 
m2 
m3 
m4 


m3, m4, 


m5, 


m6, 


sname 
*selector 


scaller sel 
;process ID 
srecipient sel 


saction 
sresult 


sread hdl 
swrite hdl 
*size 


m7, m8 
*>name 
shandle 
*action 
;size 
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use: Figure 2.1, 2.6b 


@DosOpenQueue 


use: Figure 3.25b 


@DosOpenSem 


Function Declarations and Macros Used to Interface the API 


@pw 
@pw 
@pw 
@pd 
call 
endm 


macro 
@def 
@ps 
@ps 
@ps 
call 
endm 


macro 
@def 
@ps 
@ps 
call 
endm 


use: Figure 3.21b, 3.23b 


@DosRead 


use: Figure 3.23b 


@DosReadQueue 


macro 
@def 
@pw 
@ps 
@pw 
@ps 
eal 4 
endm 


macro 
@def 
@pw 
@ps 
@ps 
@ps 
@pw 
@pw 
@ps 
@pd 


m5 
m6 
m7 
m8 
far ptr DOSOPEN 


mi, m2, ms 
DOSOPENQUEUE 
ml 

m2 

m3 


far ptr DOSOPENQUEUE 


ml, m2 

DOSOPENSEM 

ml 

m2 

far ptr DOSOPENSEM 


ml, m2, 
DOSREAD 
ml 
m2 
m3 
m4 
far ptr DOSREAD 


m3, m4 


ml, MZ, m3, 
DOSREADQUEUE 
ml 
m2 
m3 
m4 
m5 
m6 
m7 
m8 


m4, 


mS, 


m6, 


sattribute 
;openflag 
; openmode 
ae 


s;owner ID 
;handle 
;name 


shandle 
sname 


shandle 
sbuffer 
; length 
;bytesread 


m7, m8 


shandle 
;request 

; length 
saddress 
*code 
snowait 
;priority 
;semhandle 
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use: Figure 3.24b 


@DosReAllocSeg 


use: Figure 3.8 


@DosSemClear 


call 
endm 


macro 
@def 
@pw 
@pw 
call 
endm 


macro 
@def 
@pd 
call 
endm 


use: Figure 3.17b, 3.21b, 3.23b 


@DosSemSet 


macro 
@def 
@pd 
call 
endm 


use: Figure 3.17b, 3.20b, 3.22b 


@DosSemWait 


macro 
@def 
@pd 
@pd 
call 
endm 


use: Figure 3.17b, 3.20b, 3.22b 


@DosSubAlloc 


use: Figure 3.15 


macro 
@def 
@pw 
@ps 
@pw 
call 
endm 


far ptr DOSREADQUEUE 


ml, m2 

DOSREALLOCSEG 

ml 

m2 

far ptr DOSREALLOCSEG 


m1 

DOSSEMCLEAR 

ml 

far ptr DOSSEMCLEAR 


m1 

DOSSEMSET 

m1 

far ptr DOSSEMSET 


ml, m2 

DOSSEMWAIT 

ml 

m2 

far ptr DOSSEMWAIT 


ml, m2, m3 
DOSSUBALLOC 

ml 

m2 

m3 

far ptr DOSSUBALLOC 


*size 
selector 


shandle 


sehandle 


shandle 
stimeout 


sselector 
soffset 
*size 
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@DosSubSet 


use: Figure 3.15 


@DosWrite 


use: Freure 2.1, 2.66, 3.3, 3.220 


@DosWriteQueuel 


use: Figure 3.25b 


@KbdStringIn 


use; Figure 2,3, 2.2b, 2.10, 2.15, 


@VioGetPhysBuf 


use: Figure 2.3, 2.7b, 2.8, 2.10, 2.15, 3.1, 3.4, 3.6, 3.18b, 3.19 


macro 
@def 
@pw 
@pw 
@pw 
call 


macro 
@def 
@pw 
@ps 
@pw 
@ps 
call 
endm 


macro 
@def 
@pw 
@pw 
@pw 
@pd 
pw 
call 
endm 


macro 
@def 
@ps 
@ps 
@pw 
@pw 
call 
endm 


macro 
@def 
@ps 
@pw 
call 
endm 


ml, m2, m3 
DOSSUBSET 

ml 

m2 

m3 

far ptr DOSSUBSET 


ml, m2, m3, m4 
DOSWRITE 

ml 

m2 

m3 

m4 

far ptr DOSWRITE 


ml, m2, m3, m4, m5 
DOSWRITEQUEUE1 

ml 

m2 

m3 

m4 

m5 

far ptr DOSWRITEQUEUE1 


ml, m2, m3, m4 
KBDSTRINGIN 

ml 

m2 

m3 

m4 

far ptr KBDSTRINGIN 


3.1, 3.4, 3.18b 


ml, m2 

VIOGETPHYSBUF 

ml 

m2 

far ptr VIOGETPHYSBUF 
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*selector 
;flags 
ssize 


;handle 
;buffer 
; length 
sbyteswritten 


shandle 
;request 
; length 
*buffer 
;priority 


sbuffer 
; length 
siowait 
shandle 


sstructure 
sreserved 
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@VioScrLock Macro ml, m2, m3 
@def VIOSCRLOCK 
@pw m1 ;waitflag 
@ps m2 sstatus 
@pw m3 ;handle 
call far ptr VIOSCRLOCK 
endm 
use: Figure 2.3, 2.7b, 2.8, 2.10, 2.15, 3.1, 3.6, 3.18b, 3.19 
@VioScrUnLock Macro ml 
@def VIOSCRUNLOCK 
@pw m1 ;selector 
call far ptr VIOSCRUNLOCK 
endm 
use: Figure 2.3, 2.7b, 2.8, 2.10, 2.15, 3.1, 3.4, 3.6, 3.18b, 3.19 
@VioScrollUp macro ml, m2, m3, m4, m5, m6, m7 
@def VIOSCROLLUP 
@pw m1 stop 
@pw m2 sleft 
@pw m3 ; bottom 
@pw m4 sright 
@pw m5 snumber lines 
@ps m6 sattribute 
@pw m7 shandle 
call far ptr VIOSCROLLUP 
endm 
use: Figure 2.3, 2.8, 3.6, 3.17b, 3.18b, 3.20b, 3.22b 
@VioSetMode Macro ml, m2 
@def VIOSETMODE 
@ps m1 smodedata 
@pw m2 shandle 
call far ptr VIOSETMODE 
endm 
use: Figure 2.3, 2.7b, 2.10, 2.15, 3.1, 3.4, 3.18b 
@VioWrtTTY Macro ml, m2, m3 
@def VIOWRTTTY 
@ps m1 ;charstr 
@pw m2 length 
@pw m3 shandle 
call far ptr VIOWRTTTY 
endm 


use: Figure 3.17b, 3.20b, 3.21b, 3.23b, 3.24b 
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D Programs Used 
In This BOOK 


In this appendix we list the programs used in this book. Table D.1 presents each 
program, a brief description, and the page number corresponding to the program. 
Table D.2 contains the MAKE files that appear in the text. 


TABLE D.1 PROGRAMS CONTAINED IN THE TEXT 


Program Description Page 
ptr2.asm Assembler program to print “74” to generate line 46 
boxprtl.asm Assembler program to plot two lines to display 56 
scrid.asm Assembler procedure to load screen buffer 62 
prtscr.asm Assembler procedure to print the screen 65 
twoln.asm Assembler procedure to plot/print two lines 69 
graphl.asm Partial contents of GRAPHLIB.LIB dz 
connl2.asm Procedure to plot connected line 76 
slopeln.asm Program to plot connecting line 78 
bbox1.asm Procedure to generate a box 82 
llinev.asm Procedure to generate a vertical line 83 
bbox.asm Program to plot/print box 84 
twolnm.asm Modified twoln.asm that creates a screen buffer 97 
scrldm.asm Modified scrld.asm used with twolnm.asm 100 
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TABLE D.1 


Program 


prtscrm.asm 
nos2512.asm 


nos261.asm 
nos252.asm 
memseg.asm 
hugeseg.asm 
suballo.asm 
ckthl.asm 


unos251.asm 
nnos252.asm 
ckprl.asm 


os2p2.asm 
pipest.asm 
pipecl.asm 
queuest.asm 
queuecl.asm 
ioprgm.c 
Swave.c 
gphrout.c 
prtwave.c 
pprtscr.c 
pipestc.c 
pipeclc.c 
ckthred.c 
tetra.c 
rotetra.c 
rotmat.c 
rotpt.c 
DMApoint.c 
timhist.c 
dja.c 
scales.c 
scalesl.asm 
dynl.asm 
dlinkl.asm 
dyninit.asm 


Programs Used in This Book 


Description 


Modified prtscr.asm used with twolnm.asm 


Creates shared segment, child process, and prints 
screen 


Child process that generates random numbers 
Supplemental routines needed by nos2512.asm 
Program that creates and reallocates memory 
Program that allocates a huge segment 
Program that suballocates memory 


Program that sets up two threads using RAM 
semaphores 


Uses multiple threads to generate a box 
Support routines for unos251.asm 


Program that sets up two processes using system 
semaphores 


Child process using system semaphores 

Pipe main setup program 

Child process for pipe communications 

Queue main setup program 

Child process for queue example 

C program to illustrate Protected Mode 

C program to plot dynamic sinewave 

C graphic routines used in cgraph.lib 

C program to print sinewave 

C program to print screen 

C program counterpart to pipest.asm 

C program counterpart to pipecl.asm 

C program that creates a child thread 

C program for rotating tetrahedron 

C program that sets up tetrahedron 

C program that calculates rotation matrices 

C program that rotates a point 

C program that removes a point from the display 
C program that creates time-history/value database 
C program that plots Dow Jones activity 

C program to generate musical scales 
Assembler routine to generate scales 
Assembler program for preloaded DLL routines 
Assembler routine that is DLL for dynl.asm 
Initialization routine for DLL 
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Page 


101 
106 


111 
Li3 
117 
122 
126 
132 


136 
141 
146 


149 
152 
155 
158 
161 
172 
180 
183 
186 
190 
194 
196 
199 
205 
208 
209 
209 
211 
212 
215 
225 
226 
2o2 
234 
235 
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TABLE D.1 (Concluded) 


Program Description Page 
dyn22.def Definition file for load on call 236 
dyn2.asm Assembler program for run-time DLL 238 
dyn33.def Definition file for dyn2.asm 239 
gen3d.c C program that generates a surface Za 
xadiskw.c Diskwrite 256 
mmain3d.c Main calling program for 3D surface Zot 
xadiskr.c Diskread 260 
xscale.c Scales array for mmain3d.c 261 
facet3d.c Generates facets for mmain3d.c 262 
gphrout.c Plot routines 263 


Table D.2 MAKE Files Used in Text 


Program Description Page 
ioprgm.mak MAKE file for ioprgm.c 173 
swave.mak MAKE file for swave.c 178 
prtwave.mak MAKE file for prtwave.c 184 
pipestc.mak MAKE file for pipestc.c 197 
pipeclc.mak MAKE file for pipeclc.c 197 
ckthred.mak MAKE file for ckthred.c 198 
dja.mak MAKE file for dja.c 212 
gen3d.mak MAKE file for gen3d.c 254 


mmain3d.mak MAKE file for mmain3d.c 256 


E Keyboard and Mouse 
Kernel Functions 


In this book we describe the OS/2 Kernel API services which are used to access the 
full-screen mode. In this appendix we discuss the keyboard and mouse services. 
These calls cannot be used in a Presentation Manager application. 


E.1 ACCESSING THE TOOLKIT 


To employ the Toolkit functions [1] the programmer must resort to defining and 
using various assembler and C structures and databases that contain parameter infor- 
mation. These structures and data types are contained in a set of files, with exten- 
sion .inc for the assembler and a set of files with extension .h for the C compiler. 
The .h files are defined as follows (we use .h and .H interchangeably): 


Level 1: OS/2 and Presentation Manager 
OS2.H (includes OS2def.H, BSE.H, and PM.H) 
This file sets up the compiler for access to all OS/2 definitions, 
base include files, and files needed to define Presentation Man- 
ager data types, functions, and structures. 
Level 2: OS/2 
OS2DEF.H 
This file defines common constants, data types, error codes, and 
structures needed to OS/2 kernel access. 
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BSE.H 
This file allows the user to set up defined symbols such as all 
the OS/2 API kernel functions, including those that begin with 
Dos, kbd, Vio, and Mou. It includes loading of BSEDOS.H, 
BSESUB.H, and BSEERR.H. 
Level 3: OS/2 
BSEDOS.H 


This file sets up constants, structures, and function prototypes for 
the Dos services. 
BSESUB.H 


This file sets up constants, structures, and function prototypes for 
the Vio, kbd, and Mou services. 
BSEERR.H 


This file sets up error code constants for the OS/2 kernel API 
Services. 


The remaining .h files are Presentation Manager files and are only available under 
the OS/2 1.1 or higher. The .inc files are defined as follows: 


Level 1: SYSMAC.INC 


This file sets up all the API macros by calling DOSCALLS.INC 
and SUBCALLS.INC. 


Level 2: OS/2 kernel 
DOSCALLS.INC 


This file sets up all macros for Dos calls. 
SUBCALLS.INC 


This file sets up all macros for kbd, Mou, and Vio calls. 


E.2 THE KEYBOARD SERVICES 


Table E.1 illustrates the keyboard services. These are available with the IBM OS/2 
Toolkit referenced throughout the book. 


TABLE E.1 KEYBOARD FUNCTION CALLS 


Service Description 
KbdStringIn Reads a string from the keyboard and loads a buffer 
KbdCharIn Reads a character and loads the associated internal 
structure 
KbdPeek Allows examination of a character data record 
without removing it from the buffer 
KbdXlate Translates a scancode and shift key state into an 


ASCII character code, using the code page set for 
the keyboard 
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TABLE E.1 (Concluded) 


Service Description 
KbdFlush Clears the keyboard input buffer of all queued 
keystrokes 
KbdOpen/kbdClose Opening and closing a handle to a secondary logical 
keyboard 
KbdGetFocus/ Getting and releasing the input focus by the second- 
KbdFreeFocus ary keyboard 
KbdGetStatus/ Getting and setting the keyboard state 
KbdSetStatus 
KbdGetCP/ Getting and setting the ID of the system code page 
KbdSetCP used to translate scan codes into ASCII codes 
KbdSetCustXt Installing a customized keyboard translation table 
KbdRegister Registering a keyboard subsystem for the current 
session 
KbdDeRegister Canceling the registration of a keyboard subsystem 
KbdSynch Synchronizing the subsystem’s access to the physical 


E.3 THE MOUSE SERVICES 


keyboard 


Table E.2 indicates the mouse API services. Again, these services are available 
through the macros and functions defined in the IBM Toolkit. 


TABLE E.2 THE MOUSE FUNCTION CALLS 


Service 
MouOpen 


MouClose 


MouGetNumButtons 


MouGetEventMask/ 
MouSetEventMask 


MouSetDevStatus 


MouGetNumMickeys 


MouGetScaleFact/ 
MouSetScaleFact 


Description 


Initializes the mouse event queue and obtains a 
handle to access it 


Closes the mouse device for the current session 
and removes the mouse device driver handle 
from the list of valid open mouse device 
handles 

Determining the number of buttons supported 


Getting or setting the types of events reported by 
data records 


Setting mouse data to be returned in mickeys 
instead of coordinates (a mickey is a unit of 
measurement for physical mouse motion, 
whose value depends on the mouse device 
driver currently loaded) 

Determining the number of mouse motion units 
per centimeter 


Getting or setting the mickey-to-pel ratio for 
mouse motion 
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Service Description 

MouGetDevStatus Getting the state of the pointer and the event 
queue 

MouReadEventQue Reading a data record from the event queue 

MouGetNumQueEl Determining the number of records in the queue 

MouFlushQue Clearing the queue 

MouRemovePtr Defining a restricted screen area where the 

pointer is not allowed to appear 

MouFlushQue Clearing the queue 

MouRemovePtr Defining a restricted screen area where the 
pointer is not allowed to appear 

MouDrawPtr Redefining a restricted screen area, where the 
pointer is allowed to appear 

MouGetPtrShape/ Getting or setting the shape of the pointer 

MouSetPtrShape 
MouGetPtrPos/ Getting or setting the vertical and horizontal 
MouSetPtrPos positions of the pointer 

MouRegister Registering another mouse subsystem for the 
current session 

MouDeRegister Canceling the registration of a mouse subsystem 

MouSynch Synchronizing access for a mouse subsystem 


with the mouse device driver 
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Answers To Problems 


Chapter 1 


1.1. 


81CA H 


1.2. No, while OS/2 employs time slicing to share access to a single CPU among mul- 
tiple separate tasks or threads, it is not designed to service more than one CPU. 
Hence OS/2 does not provide for the parallel operation of multiple CPUs. 


4, 294, 967, 295 (22-1); +2, 147, 483, 647 (23'- 1) 


1.3. 
1.4, 


@DosExit macro 
@define 
@pushw 
@pushw 
call 
endm 
where 


@pushw macro 
mov 
push 
endm 

and 


@define macro 
ifndef 


action,result 
DOSEXIT 

action 

result 

far ptr DOSEXIT 


parm 
ax,parm 
ax 


callname 
callname 
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extrn callname: far 
endif 
endm 
1.5. @VioScrUnLock macro handle 

@define VIOSCRUNLOCK 
@pushw handle 
call far ptr VIOSCRUNLOCK 
endum 

where 

@pushw macro parm 
Mov ax,parm 
push ax | 
endm 

and 

@define macro callname 
ifndef callname 
extrn callname:far 
endif 
endm 

1.6. @VioScrLock macro wait,status,handle 

@define VIOSCRLOCK 
@pushw wait 
@pushs status 
@pushw handle 
call far ptr VIOSCRLOCK 
endm 


where @define and @pushw are defined as in the answers to Problems 1.4 and 1.5 


and 

@pushs macro parm 
mov ax,SEG parm 
push ax 
lea ax,parm 
push ax 
endm 


1.7. 1. A multitasking environment 
_ 2. A memory management facility 
3. The PM user-friendly interface 


1.8. Since we are talking about applications code, the non-system-oriented instruction set 
is applicable, and this is generally common to both CPUs with few exceptions. The 
major drawback to 80386 code is the use of references to the extended register set 
(32-bit registers): EAX, EBX, ECX, ... . While the 80286 general-purpose registers 
(AX, BX, CX, ...) are a subset of these extended registers, the converse is not true. 


1 
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1.10. 


1.11. 


1.12. 


1.13. 


1.14, 


1.15. 


1.16. 


117. 


1.18. 
1.19. 


1.20. 
1.21. 


This occurs as a result of IBM’s reservation of the last 384 KB of address space for 
special-purpose system memory, much of which is either screen buffer memory or 
ROM (read-only memory). OS/2 extended memory resides from 1 MB to 16 MB (in 
the physical address space). 


Physical memory occupies the actual hardware locations accessed by the 24 pins 
from the address lines of the 80286 CPU chip. This can be a maximum of 16 MB 
(27). Virtual memory is memory allocated in an abstract sense by the system. Since 
there are 16,384 (2'*) possible selectors with 65,536 locations per selector, there are 
a maximum total of 1,073,741,824 possible locations that can be addressed uniquely 
in this virtual space. OS/2 manages this space by mapping each segment selector to 
a segment base address through manipulation of the translation registers. Hence, if 
the available physical memory is less than 16 MB, for example, and the required 
program and data memory exceed 16 MB or the actual physical memory, OS/2 will 
move code and data to and from disk as needed. 


The Table Indicator (TT) bit in the segment selector is set for references to system 
memory. It is zero for references to local application program memory. There are 
536,870,912 locations accessible by applications in virtual memory. 


If the data communications service resided at level 0, it could preempt the CPU dur- 
ing long sessions which would mask out other, potentially more important interrupts. 
This could lead to catastrophic failure. 


The boot record loads the Machine Status Word register with a MSW that has bit 
zero set for Protected Mode operation. Subsequent loads of this register using the 
LMSW instruction can modify this state. 


1. Initialization Routine—Assembler 
2. Strategy Routine—C 
3. Interrupt Service Routine—Assembler 


A pipe references a bulk memory area, whereas a queue allows access to individual 
members of the queue. 


The API framework is more cumbersome for assembly language programs where 
software interrupts (using INT) provide immediate low-level access to the system 
hardware, for example. On the other hand, the API call orientation allows a rather 
elegant description of the services, which can enhance understanding and readability. 
In the C environment the API services are an asset, providing very readable function- 
like access to system services. 


In both cases the threads must synchronize their access. 


DosSleep. Unlike a process, the thread cannot terminate itself. Threads can be ter- 
minated only when the thread’s parent process is terminated. 


No, the Gpi services can be used only with the PM. 


Modaless because the screen context is not preempted. 


Chapter 2 


Zeke 


(a) pins 8, 6, 4, 3, and 2 
(b) pins 8, 7, 4, 2, and 1 
(c) pins 7, 5, 3, and 1 
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2.2. @VioGetPhysBuf 


Zed 


@VioScrLock 


macro 
@define 
@pushs 
@pushw 
call 
endm 


macro 
@define 
@pushw 
@pushw 
@pushw 
call 
endm 
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dstruc,rsrvd 
VIOGETPHYSBUF 

dstruc 

rsrvd 

far ptr VIOGETPHYSBUF 


wait,status,handle 
VIOSCRLOCK 

wait 

status 

handle 

far ptr VIOSCRLOCK 


2.4. The VioGetPhysBuf structure, PVBPtr1, needs to be specified as 


2.5. 


2.6. 


PVBPtrl 
bufstl 

buflenl 
physell 


freq 
dur 


@DosBeep 


waitf 
dstat 
viohdl 
PVBPtrl 
bufstl 
buflenl 
physell 


@VioScrLock 
@VioGetPhysBuf 
push physell 
pop es 

mov dh,25 
mov, dal1,154 
mov bx,75 

mov cx,235 
call connl2 
@VioScrUnLock 


label FAR 

dd OAO0000H 

dd 6D60H 

dw 0 

dw 5000 

dw 1000 
freq,dur 

equl 

db ? 

equ 0 

label FAR 

dd 0OB8000H 

dd 4000H 

dw 0 

waitf,dstatk,viohdl 

PVBPtr1,viohdl 

viohdl 
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dels 


2.8. 


2.9. 


2.10. 


2.11. 


2.12. 


2.13. 


2.14, 


2.15. 
2.16. 


kbd_buf db 80 

lkbd_buf dw $-kbd_buf 

jiowait dw 0 

kbdhdl equ 0 

freq dw 1000 

dur dw 5000 
@KbdStringin kbd_buf,1lkbd_buf, iowait,kbdhdl 
@DosBeep freq,dur 


Yes, all calls to the API can be made in full form, where each push and pop, as 
well as EXTRN declaration, is stated explicitly according to the rules of OS/2. The 
toolkit simply provided a set of assembler .inc files and C .h files that facilitated 
usage of the API services through very functional macros. 


The key assumption is that segment selectors can be treated as segment addresses. 
Since the 80286 accesses segments using the selectors, the selector value must reside 
in a segment register. The address is then calculated in the usual Protected Mode 
fashion, where the segment selector acts as a segment address. The use of segment 
override addressing, such as 


es: [bp] 


simply permits specification of an address in the usual fashion, where the segment 
selector is made to correspond to the physical segment address when VioGetPhysBuf 
is exercised. 


They represent FAR locations because the entry points are called from external API 
modules, hence a 32-bit address must be specified. 


No hierarchy should have a single child subordinate to a parent. The box 310 should 
be absorbed in 300. 


The command is 
@DosWrite dev_hand,in_buffer5,bytesin3,bytesout 
where the undefined parameter is 


in _buffer5 db 1BH,41H,0CH 


It is intuitive that they cannot be preempted by an OS/2 task switch, or the possibil- 
ity of losing data from the device would occur. 


To access the screen buffer (physical) properly, the screen must be locked; hence if 
scr_Id is to load scr_buffer with the screen context, it must be locked. If prtscr is 
executed when the screen is locked, it could dominate access time for the physical 
display buffer. Hence the program should load a temporary buffer, release the screen 
context, and then begin the print operation. 


Ten complete raster segments. 


The DosExitCritSec corresponds to exit of a critical section of execution for a thread 
and returns control to a process. This could be used, for example, when an_inde- 
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2.17. 


Answers To Problems 


pendent thread has a particular piece of code that must execute prior to any other 
operation for the parent process. Then it would be desirable to monitor and ensure 
that this code executed, before continuing. Clearly, this could be dynamic and change 
with the active chronology of execution. 


DosExit is used to terminate an application and return to OS/2. All other returns 
NEAR or F. 


Chapter 3 


3.1. 


3.2. 


J. 


3.4. 


ane 


The drivers mentioned operate from the kernel, level 0. They must originate here 
because they have to be protected ahead of all other code. We cannot have a disk- 
write preempted in the middle, nor can we tolerate “jerky” mouse cursor movement 
as the mouse position changes. 


The macro calls admittedly remove a layer of detail from the program code. This 
layer would tend to expand the code by a factor of 4 to 7. All the pushes to the 
Stack have been suppressed prior to each API call and the call takes on the form of 
a higher-level-language (HLL) function call. The data area tends to expand consid- 
erably with all the macro parameter definitions, but the actual executable code re- 
mains compact. This requires the programmer to develop a general familiarity with 
the macro calls at the level of the IBM Programmer’s Toolkit or Appendix C of this 
book. Once this familiarity has developed it is a very easy matter to read the result- 
ing “structured” code and follow the flow of execution. Hence maintenance becomes 
an easy task. Clarity (of how the code executes) is also paramount, and much more 
so under the macro call format. The macro calls do, however, inhibit debugging in 
that the in-line code is missing. If the user prints a copy of the list file with macros 
expanded, tracing the source code is still an easy matter. In general, these approaches 
tend to be a matter of preference based on the programmer’s orientation. We favor 
the HLL appearance of the code. It makes functional performance of the code the 
primary mechanism to be emphasized. Expansion of the in-line code makes it more 
obscure from a functional viewpoint but easier (and essential) to debug. 


For the segment to be sharable, bit 0, to be sharable through @DosGiveSeg, or bit 1, 
to be sharable through @DosGetSeg, must be set in the flags word (the third pa- 
rameter in the calling list). Bit 2 of this same flags word must be set if the segment 
is to be discardable. 


The write to the huge segment must use the proper selector. When crossing the 64K- 
byte boundary the program must access a new but contiguous selector. 


There must be some common link between the two processes. Usually, this is a 
common element name such as 


\SEM\SDAT.DAT 
or 
\QUEUES\QDAT.DAT 


which appears in both processes and is the same. The system then provides the con- 
nection. Alternative to this is the passing of a selector or printer in a common 
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memory area such as a shared segment defined using 
\SHAREMEM\SDAT . DAT 
where the path is common to both processes. 


3.6. RAM semaphores are a good candidate for intertask communications when each 
thread is within the same process. When conducting interprocess communications, 
system semaphores provide a good method for synchronization because they share a 
common system memory area and can be passed back and forth. 


3.7. The macro @pushs loads a 32-bit address for parm on the stack. The macro @pushd 
loads the 32-bit contents of the double-word parameter parm onto the stack. The 
fourth parameter of @DosWriteQueue must contain a pointer value, and the address 
of this the double word containing this value is not of interest. 


3.8. By clearing the semaphore using @DosSemClear. 


3.9. There could be a segment protection violation, as both processes contend for the 
speaker. 


3.10. A pipe was used to pass buffered data directly. The queue, on the other hand, was 
used to pass pointers to buffers. The queue employed a shared memory area allo- 
cated by @DosAllocSeg, whose buffer address was passed via the queue. 


3.11. See Table 3.1. 


3.12. A shared segment is allocated with @DosAllocShrSeg and is used when two or more 
processes need to access a common buffer in interleaved or multiple asynchronous 
fashion. The fact that both have simultaneous access must be regulated using sema- 
phores, for example. A giveable segment, on the other hand, would be used when a 
process desires to write to a common segment and then release the segment so that 
another process can access the “given” segment. 


3.13. Process 1 


read_hdl dw ? 

write hdl dw ? 

buf flag dw 256 ;for example 

bytes_ written dw ? 

msize dw ? 

ssell dw rs 

shrname db ‘\SHAREMEM\SDAT1.DAT’ , 0 
@DosAllocShrSeg msize,shrname,msell ;allocate segment 
@DosMakePipe read_hdl, write_hdl, buf_flag ;Create pipe 


@DosCreateSem cee ; Synchronize 
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@DosWrite write_hdl,message,length,bytes written ;Transfer 


@DosSemSet es ;set semaphore 
@DosExecPgm 5 a ;execute child 

@DosWait oor ;wait child completion 
Process 2 


shrsel dw ? 

shrname db ’\SHAREMEM\SDAT1.DAT’,0 

read hdl ... 

bytes _ read ... 

@DosOpenSem ... ;Open semaphore 

@DosGetShrSeg... get shared segment 

;load read handle and message length from shared segment 
buffer 


@DosRead read_hdl, buffer, length, bytes_read ;read buffer 


@DosSemClear ... ;clear semaphore 


3.14. Process 1 


q hdl dw ? 
q name db ‘\QUEUES\QDAT.DAT’ ,0 


@DosCreateQueue q_hdl,... ;create queue 
@DosExecPgm... sexecute child 
@DosReadQueue q_hdl,... sread queue buffer 


stransfer message using 32-bit queue pointer to buffer 


@DosFreeSeg... ;free allocated segment (process) 
@DosCloseQueue... ;close queue 

Process 2 

q_ hdl dw ? 


q name db ‘\QUEUES\QDAT.DAT’ ,0 
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3.16. 


q_w dw 0 

qv dd 0 

q Ex dw 0 

@DosOpenQueue ... ;Open queue 
@DosAllocSeg... sallocate segment 


;load segment with message 


@DosGiveSeg... ;get read selector 
@DosWriteQueuel... ;write address to queue 
@DosFreeSeg qw ;free allocated segment 


@DosCloseQueue... 


The intraprocess thread appears as a FAR entry point within the same process seg- 
ment. An interprocess thread appears as a FAR call to an entry point in a new seg- 
ment, and it must be started with DosExecPgm. 


The calls 


@DosAllocSeg 
@DosReAllocSeg 


actually create and reallocate global memory space. This memory can exist as vir- 
tual addresses (on disk) or as actual data RAM. The call 


@DosSubAlloc 


subdivides an existing segment into smaller blocks of local memory. This call returns 
a block offset to be used as the start of the memory block. No consideration of pre- 
vious writes to the segment is made; hence a block can overwrite a memory area if 
not properly handled. A recommended procedure is to suballocate the memory seg- 
ment as early as possible, thereby obtaining a block offset from which to work. 


Chapter 4 


4.1. 


4.2. 


When IBM and Microsoft developed the two versions of the Toolkit, they modified 
the structures and calling sequences between them. Calling the physical screen buffer 
in Version 1.0 required a structure PhysBufData. In the Version 1.1 this structure 
was renamed _VIOPHYSBUF and the structure members have different tags between 
versions. Hence many of the Version 1.1 Toolkit entities require slightly different no- 
menclature than that of Version 1.0. 


Many of the Standard C I/O library functions have been defined under Microsoft C 
Optimizing Compiler Version 5.1 to run as reentrant routines. Hence these library 
routines are callable in the usual fashion from Protected Mode. 
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4.8. 


4.9. 


4.10. 
4.11. 


4.12. 


4.13. 


Answers To Problems 


All formal parameters specified as type int need not be type specified in the formal 
parameter list. Hence, when passing parameters, only types other than int need be 
specified. 


The input value x is of int type, hence can be signed. The range of such signed 
variables is [—32,768, 32,768]. Had this parameter been of type double or float, a 
much greater range of values would be permissible. 


The normal C local stack calling convention starts with the Nth parameter and con- 
tinues to load the stack down to parameter 1. The API services require conventional 
loading from parameter 1 to N. In the Toolkit a type APIENTRY is defined using 
the pascal convention, which reorders the formal parameters on the stack from 1 to 
N. 


The code 
CHAR FAR *ptr; 


defines a FAR pointer, ptr, which points to a byte value using a 32-bit address. The 
code 


CHAR FAR *shrname = “”\\SHAREMEM\\SDAT1.DAT”; 


defines a FAR pointer, shrname, which points to a string value using a 32-bit ad- 
dress and associates the string value with this 32-bit address. 


This function generates a full 32-bit address for a FAR call. The variables sel and 
off correspond to selector and offset, respectively, and must be obtained separately. 


This declaration associates a FAR pointer address of 0xB8000 with a BYTE value 
specified as the structure element PVBPrt2.pBuf. Note that this structure element is 
specified as part of the physical buffer structure WIOPHYSBUF. The value in ques- 
tion is the start address (32-bit) for the physical screen buffer. 


The return from sin() is double precision; hence the defining relation should be 


y = (float)(sin(2. * PI * t)); 


The dot attribute for wdot() is 1, and the dot attribute for uwdot() is 0. 


The column values represent horizontal increments, and the row values represent ver- 
tical increments. 


This is the character code for putting the Epson dot matrix printer (FX-85) into 
graphics mode. The values 0x1B and Ox4V specify 


ESC k 


and 64 is the difference between 256 and 320. Here the “1” indicates one block of 
256 columns plus “64,” to get 320 columns in the printer graphics mode. The ESC k 
indicates that the printer must go to graphics mode. 


This sends the Epson FX-85 printer the command 


ESC A 8 
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4.15. 


4.16. 


4.17. 


4.18. 


4.19. 


which changes the printer output to case 8/72-inch spacing for lines. This removes 
any extra vertical spacing that might appear in the output and ensures that the eight 
dots of vertical spacing will butt together as each vertical set of pins is executed for 
each line (25 vertical lines of eight pins per line). 


RAM semaphores. 


The calls all employ type definitions for the formal parameters unless the parameters 
are of basic integer type (such as INT, UINT, USHORT, SHORT). 


One process must establish the semaphore, open the second process, and wait until 
the second process is complete. The second process maintains synchronization by 
executing with the first process blocked until 


DosSemClear() 


is issued by the second process. This allows the first process to cease being blocked 
by 
DosSemWait() 


and continue execution beyond this instruction. Threads are handled in identical fash- 
ion. 


To pass the pipe read handle, read_hdl, to the second process, where it is used to 
locate the pipe buffer and transfer the pipe message using 


DosRead( ) 


The thread’s stack is separate from the calling thread’s stack. Hence the compiler 
will detect an overflow condition because the second thread’s stack is “outside” the 
stack originally defined for the overall process. To avoid compiler errors with the 
Microsoft C Optimizing Compiler Version 5.1, for example, a compiler option of -Gs 
must be used. 


The programs have been debugged and it is assumed that no error checking is 
needed intrinsically. Good form would retain such error checking when dynamic er- 
rors can creep in. For clarity, we have avoided them in the code dynamics. 


4.20. The points 
(x,y,z) = (1, 0, 0) 
(0, 1, 0) 
(0, 0, 0) 
(0, 0, 1) 
4.21. From the library cgraph.lib. 
Chapter 5 
5.1. Load the routine as a run-time dynamic linker library (DLL). 


Side 


The dynamic link library (.dll) executable module is generated from a group of ob- 
ject modules as 


link (group object modules), 
(.dll module),,(libraries),(.def module) 
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5.8. 


5.9. 


5.10. 
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Here the definition file must start with the LIBRARY keyword. Next, the .lib file is 
created from 


implib (.lib file) (.def module) 


This definition file is the same one used earlier to define the .dll module. 


. The return address offset. 
5.4. 
5.5. 


It appears in the definition file with LIBRARY, not NAME. 


EXPORTS are the names of routines contained in a DLL which will be available to 
be called by other modules. IMPORTS are the names of external routines to be used 
by the DLL. 


The two services needed are 


DosLoadModule 
DosGetProcAddr 


The first is required to load the run-time .dll file, which must be specified in the ini- 
tial calling program. This is the calling program’s link with the DLL. The second is 
needed to specify the DLL procedure entry point so that a simple FAR call to this 
entry point can be made. 


You would choose a flowchart because it illustrates the dynamic decision-oriented 
performance of the program. There are several types of flowcharts: literal and func- 
tional. The former spell out each individual programming step and tend to be very 
detailed. Functional flowcharts are more desirable and address program activity in a 
functional sense; that is, each block constitutes a major activity in the sequence of 
program flow, and this activity usually consists of many program steps. A Structure 
Chart merely illustrates the subordinate relationships among the program components. 
This device is most useful for providing the user with an overview of the program 
and a general picture of the major modules appearing in the program. 


The dominant characteristic of a C function is a single entry and exit point and a 
single return value. These features serve to make the program structure very orderly 
with a downward flow of activity to the code instead of the varied branching found 
in programs typified by FORTRAN code, for example. In FORTRAN programs, the 
unrestricted use of GOTOs and conditional branching frequently makes following the 
program flow difficult. 


C programs can efficiently use global variables when large array components of da- 
tabases are to be manipulated. In this case the use of arrays as local variables would 
greatly expand the stack area and result in inefficient memory allocation. The diffi- 
culty with using global variables in any implementation is that external modules that 
call such variables frequently lose track of the time history of the variables. By treat- 
ing variables as locally defined, the complete time picture of the performance of the 
variable is available in the accessing module. 


This is accessible only through the Presentation Manager, which did not become 
available until OS/2 Version 1.1 was issued. 


Three-dimensionally the x-axis points out of the image away from the plane of the 
CRT. Hence a two-dimensional display, such as a CRT, can only illustrate the image 
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5.13. 


5.14. 


3,15. 


of a three-dimensional surface as it is projected onto such a two-dimensional display. 
This projection is achieved by setting one of the coordinate sets equal to zero. 


Some of the hidden facets appearing in the three-dimensional surface of Figures 5.19 
through 5.23 actually have positive direction normals to the facet surface. Hence 
these surfaces, even though hidden, will not satisfy the criterion that the normal 
points into the plane of the CRT. 


This equation has the form 


ae 
; sin’ u 
lim, A* —.— 
u—0 u 


using 
3 DB} 
smu = uo — at + 3 — 
This becomes 
2 4 : 
, 2 _ H u _ — £3 
dim, A E 31 + 5 ee | = A 


This routine must be called before setting the CGA mode because it prints a request 
to the text screen (asking for the name of the data file). 


The selector, MMI, would no longer be referenced. 
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